Functions

call

call(rawOpcodes, *functionArgs)

Call embedded C code.

This function is for advanced users only. There is a separate Application Note that covers how to use this advanced feature.

Parameters

  • rawOpcodes (str) – Machine code that implements the function to be called.

  • *functionArgs (arbitrary argument list) – Parameters depend on the actual function implemented by rawOpcodes.

callback

callback(callback, remoteFunction, *remoteFunctionArgs)

It is easy to invoke functions on another node using the rpc() built-in function; however, to get data back from that node, you either need to put a script in that node to explicitly send the value back, or use the callback() function.

Parameters

  • callback (str) – Specifies which function to invoke on the originating node, passing in the return value of the remote function.

  • remoteFunction (str) – Specifies which function to invoke on the remote node.

  • *remoteFunctionArgs (arbitrary argument list) – Used if the remote function takes any parameters.

Returns

Normally returns True, but it does not mean your RPC request was successfully sent and received

Returns False only if it was unable to attempt the Remote Procedure Call (for example, if the node is low on memory).

Return type

bool

Examples

Imagine having a function like the following in SNAP node A:

def showResult(obj):
    print str(obj)

Invoking callback('showResult', 'functionOnB') on node B will cause function showResult() to get called on node A with the result of function functionOnB() on remote node B.

The remoteFunction parameter can take parameters, so node A could also invoke the following on node B by passing 0 to the readAdc() function:

callback('showResult', 'readAdc', 0)

Node B would invoke readAdc(0) and then remotely invoke showResult(the-actual-ADC-reading-from-readAdc(0)) on node A.

The callback() function is most commonly used with the rpc() function:

rpc(nodeB, 'callback', 'showResult', 'readAdc', 0)

Essentially, callback() allows you to ask one node to do something and then tell you how it turned out.

Note

Even if you do not have a script that explicitly sends the return value back, you still must have some script in a node before you can call any function, including any of the built-in functions by name.

See also

callout

callout(nodeAddress, callback, remoteFunction, *remoteFunctionArgs)

This function is similar to callback(), but instead of the final result being reported back to the originating node, you explicitly provide the address of the target node.

Parameters

  • nodeAddress (str) – Specifies the SNAP address of the target node that is to receive the callback.

  • callback (str) – Specifies which function to invoke on the target node passing in the return value of the remote function.

  • remoteFunction (str) – Specifies which function to invoke on the remote node.

  • *remoteFunctionArgs (arbitrary argument list) – Used if the remote function takes any parameters.

Returns

Normally returns True, but it does not mean your RPC request was successfully sent and received.

Returns False only if it was unable to attempt the Remote Procedure Call (for example, if the node is low on memory).

Return type

bool

Examples

Node A could invoke the following on node B, which would automatically invoke node C:

callout(nodeC, 'showResult', 'readAdc', 0)

Node B would invoke readAdc(0) and then remotely invoke showResult(the-actual-ADC-reading-from-readAdc(0)) on node C.

The callout() function is most commonly used with the rpc() function:

rpc(nodeB, 'callout', nodeC, 'showResult', 'readAdc' ,0)

Essentially, callout() allows you to have one node ask another node to do something, and then tell a third node how it turned out.

Note

To understand this function, you should first be comfortable with using the rpc() and callback() built-ins.

See also

chr

chr(number)

Translates an ASCII code into a single-character string.

Parameters

number (int) – ASCII code as an integer.

Returns

A single-character string based on the number given.

Return type

str

Example

Ways to obtain the string 'A':

chr(0x41) # returns the string 'A'
chr(65)   # so does this

crossConnect

crossConnect(dataSrc1, dataSrc2)

Cross-connect SNAP data sources.

Parameters

  • dataSrc1 (int) – SNAP data source.

  • dataSrc2 (int) – SNAP data source.

Returns

None

See also

dmCallout

dmCallout(dstAddrs, dstGroups, ttl, delayFactor, callback, remoteFunction, *remoteFunctionArgs)

New in version SNAP 2.7.

Warning

If you provide a dstAddrs that is not a multiple of three characters in length, the call will fail and no message will be sent to any node.

Parameters

  • dstAddrs (str) – A string containing concatenated addresses of the target nodes that are to receive the final (result) function call.

  • dstGroups (str) – Specifies which nodes should receive the outgoing message, based on their multicast processed groups. By default, all nodes belong to the broadcast group 0x0001.

  • ttl (int) – Specifies the Time To Live (TTL) for the request. This specifies how many hops the message is allowed to make before being discarded.

  • delayFactor (int) – Provides a mechanism to allow remote nodes to stagger their responses to the message. The parameter should be a one-byte integer specifying the amount of time, in milliseconds, that should pass between node responses, among the nodes targeted by the request. Setting this parameter to zero allows all remote nodes to respond immediately, which may cause packet loss due to interference.

  • callback (str) – Specifies which function to invoke on the originating node, passing in the return value of the remote function.

  • remoteFunction (str) – Specifies which function to invoke on the remote node.

  • *remoteFunctionArgs (arbitrary argument list) – Used if the remote function takes any parameters.

Returns

This function normally returns True; however, it does not mean your RPC request was successfully sent and received.

It returns False only if it was unable to attempt the Remote Procedure Call (for example, if the node is low on memory or the RPC was too large to send).

Return type

bool

Note

As with a dmcastRpc(), any node that finds its address when it receives the multicast message will act on the message (assuming that the multicast processed groups setting is compatible). Also as with dmcastRpc(), if you pass an empty string as the dstAddrs parameter, the outgoing message will behave as a regular mcastRpc() call.

See also

dmcastRpc

dmcastRpc(dstAddrs, dstGroups, ttl, delayFactor, remoteFunction, *remoteFunctionArgs)

New in version SNAP 2.6.

Directed multicast provides a means to send an RPC call to a list of remote nodes without incurring the route discovery overhead necessary for addressed RPC calls.

Parameters

  • dstAddrs (str) –

    A string containing concatenated addresses for any nodes you wish to act on the directed multicast.

    If you provide an empty string (""), all remote nodes that receive the message that would otherwise act on the message (subject to the dstGroups parameter and the existence of the function in the remote node’s script) will act on the request as though the call were a regular mcastRpc() call; however, in this case added features available only for directed multicast (such as information available through several getInfo() calls) are also available.

  • dstGroups (str) – Specifies which nodes should respond to the request. By default, all nodes belong to the broadcast group 0x0001.

  • ttl (int) – Specifies the Time To Live (TTL) for the request. This specifies how many hops the message is allowed to make before being discarded.

  • delayFactor (int) – Provides a mechanism to allow remote nodes to stagger their responses to the request. The parameter should be a one-byte integer specifying the amount of time, in milliseconds, that should pass between node responses, among the nodes targeted by the request. Setting this parameter to zero allows all remote nodes to respond immediately, which may cause packet loss due to interference.

  • remoteFunction (str) – Specifies which function to invoke on the remote node.

  • *remoteFunctionArgs (arbitrary argument list) – Used if the remote function takes any parameters.

Returns

This function normally returns True; however, it does not mean your RPC request was successfully sent and received.

It returns False only if it was unable to attempt the Remote Procedure Call (for example, if the node is low on memory or the RPC was too large to send).

Return type

bool

Warning

If you provide a dstAddrs that is not a multiple of three characters in length, the call will fail and no message will be sent to any node.

See also

eraseImage

eraseImage()

This function is used by Portal and SNAPconnect as part of the script upload process and is not normally used by user scripts. Calling this function automatically invokes the resetVm() function before erasing the image (otherwise the SNAPpy VM would still be running the script, as you erased the image out from under it).

Returns

None

errno

errno()

Returns the most recent error code from the SNAPpy Virtual Machine (VM), clearing it out as it does so.

If you receive an UNSUPPORTED_OPCODE, UNRESOLVED_DEPENDENCY, BAD_GLOBAL_INDEX, or BAD_CONST_INDEX error, please contact Synapse Wireless support and provide your SNAPpy script. These errors should not be reachable with a SNAPpy script, unless you are manipulating memory behind-the-scenes with pokes or with callable C strings.

The EXCEEDED_MAX_BLOCK_STACK and EXCEEDED_MAX_OBJ_STACK errors have been retired from SNAPpy code and can no longer be generated.

Returns

The most recent error code.

Return type

int

The possible error codes are:

Value

Enumeration

Possible Cause

0

NO_ERROR

1

OP_NOT_DEFINED

Are you trying to add or compare things where that is not an option, such as adding two functions, or two Nones?

2

UNSUPPORTED_OPCODE

3

UNRESOLVED_DEPENDENCY

4

INCOMPATIBLE_TYPES

Are you trying to add a number to a string?

5

TARGET_NOT_CALLABLE

Are you trying to invoke foo(), but foo = 123?

6

UNBOUND_LOCAL

Are you trying to use a variable before you put something in it?

7

BAD_GLOBAL_INDEX

8

EXCEEDED_MAX_BLOCK_STACK

Are you calling a function recursively to too great a depth, or having too many nested layers of function calls?

9

EXCEEDED_MAX_FRAME_STACK

10

EXCEEDED_MAX_OBJ_STACK

11

INVALID_FUNC_ARGS

Are you passing the wrong type of parameters to a function? Are you passing the wrong quantity of parameters?

12

UNSUBSCRIPTABLE_OBJECT

Are you trying to slice or index something other than a string, tuple, or byte list?

13

INVALID_SUBSCRIPT

Are you trying to access str[3] when str = ‘ABC’? (When str = ‘ABC’, str[0] is ‘A’, str[1] is ‘B’, and str[2] is ‘C’.)

14

EXCEEDED_MAX_LOCAL_STACK

Do you have too many local variables? Have you passed a large number of variables to nested levels of function calls?

15

BAD_CONST_INDEX

16

ALLOC_REF_UNDERFLOW

Do you have more than 255 variables referencing the same buffer, such as a single string buffer? If so, as SNAP creates references to them with its one-byte reference counter, it will wrap past zero (causing an ALLOC_REF_OVERFLOW error), and as it releases references to them, it will wrap down past zero generating this error. (Debug builds only.)

17

ALLOC_REF_OVERFLOW

Do you have more than 255 variables referencing the same buffer, such as a single string buffer? If so, as SNAP creates references to them with its one-byte reference counter, it will wrap past zero, generating this error, and as it releases references to them, it will wrap down past zero (generating an ALLOC_REF_UNDERFLOW error.) (Debug builds only.)

18

ALLOC_FAIL

Are you trying to keep too many string results? As of version 2.2, you are no longer limited to a single buffer for each type of string operation, but they are still limited in number.

19

UNSUPPORTED_TYPE

Have you tried to save an unsupported type, such as a tuple or iterator, to an NV parameter, or are you trying to pass an unsupported type (tuple, iterator, or byte list) in a SNAP packet?

20

MAX_PACKET_SIZE_EXCEEDED

Are you passing too large of a string value?

21

MAX_STRING_SIZE_EXCEEDED

Have you created a dynamic string too large for your platform?

22

EXCEEDED_C_DATA_SIZE

Your C code is trying to use more space for data than the firmware allows. Normally, this would be caught at compile time. However, if you get this error, the SNAP firmware has ignored your script and will not run it to prevent it from causing problems. To fix this, build your script using the firmware version currently running on the node.

23

INVALID_C_METADATA

The C code in the provided script was not compiled for the firmware image currently running. If you get this error, the SNAP firmware has ignored your script and will not run it to prevent it from causing problems. To fix this, build your script using the firmware version currently running on the node.

Note

If you are including C code in your SNAPpy script, your C code can use the pyerr macro to return one-byte error codes of your own definition. You can also use this as a way to return a second value from your C functions.

flowControl

flowControl(uart, isEnabled, isTxEnable)

Allows you to enable/disable flow control. Without flow control, there is a greater chance that characters will be dropped during communication; however, disabling flow control frees up two more pins (per UART) for use as other I/O. The initial state of flow control is set by bits 0x0080 (UART 1) and 0x0020 (UART 0) in NV11 - Feature Bits. By default, flow control is enabled. However, SNAP serial communications between nodes make no use of flow control.

When flow control is enabled, the SNAP node monitors the RTS pin from the attached serial device. As long as the SNAP node sees the RTS pin low, the node will continue sending characters to the attached serial device (assuming it has any characters to send). If the SNAP node sees the RTS pin go high, then it will stop sending characters to the attached serial device. By default, the SNAP node uses the CTS pin as a Clear To Send indication when flow control is enabled. The CTS pin indicates whether the SNAP node can accept more data. The CTS pin goes low if the SNAP node can accept more characters. The CTS pin goes high (temporarily) if the SNAP node is “full” and cannot accept any more characters. (The connected serial device can keep sending characters, but they will likely be dropped.)

It is important to realize that UART handshake lines are active-low. A low voltage level on the CTS pin is a boolean False but actually means that it is “Clear To Send.” A high voltage level on the CTS pins is a boolean True but actually means it is not “Clear To Send.” RTS behaves similarly.

The CTS pin can optionally act as a Transmit Enable (TXENA) indication using the isTxEnable parameter. In this mode, the CTS pin is normally high and transitions low before any characters are transmitted, remaining low until they have been completely sent.

When flow control is disabled, both the RTS and CTS pins are ignored.

Parameters

  • uartNum (int) – Specifies the UART (0 or 1).

  • isEnabled (bool) – Enables/disables hardware flow control.

  • isTxEnable (Optional[bool]) – Controls CTS behavior when flow control is enabled. If True, CTS acts as a TXENA pin. If False, CTS acts as Clear To Send. (Default is False.)

Returns

None

Note

Remember that some SNAP nodes may have only one UART available. The RF266, based on the AT128RFA1, has two UARTS, but only UART1 comes out to pins on the module.

getChannel

getChannel()

Get the SNAP channel (0-15) for SNAP devices operating in the 2.4 GHz range, which corresponds to the 802.15.4 channel.

Returns

SNAP channel that the node is currently on.

Return type

int

Possible return values are:

SNAP Channel

802.15.4 Channel

0

11

1

12

2

13

3

14

4

15

5

16

6

17

7

18

8

19

9

20

10

21

11

22

12

23

13

24

14

25

15

26

getEnergy

getEnergy()

Returns a number indicating the result of a brief radio Energy Detection scan on the currently selected channel, providing an indication of the noise floor for radio energy at that frequency.

Returns

Energy detected on the current channel in (-) dBm.

Return type

int

See also

getI2cResult

getI2cResult()

Returns the status code from most recent I2C operation, clearing the value in the process.

Returns

Result of the most recently attempted I2C operation.

Return type

int

The possible return values are:

Value

Enumeration

Meaning

0

I2C_OFF

I2C was never initialized

1

I2C_SUCCESS

The most recent I2C operation succeeded

2

I2C_BUS_BUSY

I2C bus was in use by some other device

3

I2C_BUS_LOST

Some other device stole the I2C bus

4

I2C_BUS_STUCK

There is a hardware or configuration problem

5

I2C_NO_ACK

The slave device did not respond properly

Note

This function can only be used after function i2cInit() has been called.

See also

  • User Guide on I2C

getInfo

getInfo(whichInfo)

Provides information about the RPC command currently being processed.

Parameters

whichInfo (int) –

Specifies the type of information to be retrieved.

Value

Information Returned

0

Vendor

1

Radio

2

CPU

3

Module Family

4

Build

5

Version (Major)

6

Version (Minor)

7

Version (Build)

8

Encryption

9

RPC Packet Buffer

10

Is Multicast

11

Remaining TTL

12

Remaining Small Strings

13

Remaining Medium Strings

14

Route Table Size

15

Routes in Route Table

16

Bank Free Space

17

Reserved

18

STDIN Hook Trigger

19

Remaining Tiny Strings

20

Remaining Large Strings

21

Script First Run

22

Script Base Address

23

Script Base Bank

24

Is Directed Multicast

25

Read and Reset Delay Factor (Directed Multicast Only)

26

Address Index (Directed Multicast Only)

27

Multicast Groups (Multicast & Directed Multicast Only)

28

Original TTL (Directed Multicast Only)

29

C Compiler ID

30

Build ID

Returns

Varies based on the value of whichInfo.

Return type

int

Vendor

Indicates the manufacturer of the radio module on which SNAP is running. Possible return values for getInfo(0):

Value

Manufacturer

0

Synapse

2

Freescale

3

CEL

4

ATMEL

5

Silicon Labs

7

PC

9

STMicrosystems
Radio

Indicates the method the node uses to connect to the rest of the network. Possible return values for getInfo(1):

Value

Method

0

802.15.4-based 2.4 GHz

1

None (Serial only)

3

868 MHz

4

Powerline

5

900 MHz Frequency-Hopping

6

802.15.4-based 900 MHz
CPU

Indicates the processor paired with the radio in the SNAP module. Possible return values for getInfo(2):

Value

Processor

0

Freescale MC9S08GT60A

1

ZIC 8051

2

MC9S08QE

3

Coldfire

4

ARM7

5

ATmega

6

Si100x 8051

7

X86

8

UNKNOWN

10

ARM CORTEX M3
Module Family

Indicates the module family. Possible return values for getInfo(3):

Value

Module Family

0

Synapse RF100 SNAP Engine

3

CEL ZIC2410

5

MC1321x

6

ATmega128RFA1

7

SNAPcom

8

Si100x

9

MC1322x

11

Si100x KADEX

13

Synapse RF300 SNAP Engine

14

Synapse RF200 SNAP Engine or SNAPstick 200

15

Synapse SM300 Surface Mount Module

16

Synapse SM301 Surface Mount Module

17

Synapse SM200 Surface Mount Module

19

Synapse RF266

20

STM32W108xB

27

Synapse SM220 Surface Mount Module, RF220UF1 SNAP Engine, or SNAPstick 220

30

Synapse RF220SU SNAP Engine

31

Synapse RF220SU-EU SNAP Engine
Build

Indicates whether the firmware in your SNAP module is a debug or release build. Possible return values for getInfo(4):

Value

Type

Trade-offs

0

debug

More error checking, slower speed, less SNAPpy room

1

release

Less error checking, faster speed, more SNAPpy room
Version

Indicates the Major, Minor and Build components of the firmware version. By using getInfo(5), getInfo(6), and getInfo(7), you can retrieve all three digits of the firmware version number.

Encryption

Indicates the type of encryption that is available in the module; however, it does not indicate what encryption (if any) is enabled for the module. Possible return values for getInfo(8):

Value

Encryption Support

0

Deprecated

1

AES-128

2

Basic encryption
RPC Packet Buffer

After you make an RPC call, a call to getInfo(9) returns an integer indicator of the packet buffer number used for the RPC call. That integer can be used in a function hooked to the HOOK_RPC_SENT event to determine that the processing of the packet buffer is complete. See the HOOK_RPC_SENT details for more information.

Is Multicast

Indicates how the RPC command currently being processed was invoked. Possible return values for getInfo(10):

Value

Meaning

0

Received via an addressed RPC command or was triggered by a system hook

1

Received via a multicast or directed multicast
Remaining TTL

Indicates how many “hops” the RPC command currently being processed had left before its end-of-life. You can use this information to tune your TTL values for your network to reduce broadcast chatter. This value is valid for both multicasts and directed multicasts, but not for addressed RPC commands.

Remaining Small Strings

Indicates how many “small” string buffers remain unused in your node. The size and number of small strings available on your node will vary depending on the underlying hardware and firmware.

Remaining Medium Strings

Indicates how many “medium” string buffers remain unused in your node. The size and number of medium strings available on your node will vary depending on the underlying hardware and firmware.

See also

Refer to SNAP Modules

Route Table Size

Indicates how many other nodes your node can keep track of in its address book. When a node needs to talk to another node, it must ask where that node is. It will find one of three things: that it can talk to the node directly, that it must communicate through another node, or that it cannot find the node at all. In these first two cases, SNAPpy keeps track of the path used to contact the node in a route table, so the next time it talks to the same node it does not have to query how to find the node first. How long the path to a node is kept depends on the mesh routing timeouts defined in the following NV parameters:

See also

User Guide on Preserving Unicast Routes

Routes in Route Table

Indicates how many of the routes in the node’s route table are in use, meaning how many other nodes the current node knows how to access without having to first perform a route request.

Bank Free Space

This query is only supported on platforms that support OTA Firmware Upload (it returns a value of 0 on the other platforms). This is how Portal knows if a given firmware image (.sfi file) will “fit” into the node.

STDIN Hook Trigger

Indicates what kind of data input event occurred that would have triggered HOOK_STDIN. Possible return values for getInfo(18):

Value

Meaning

0

In line mode, an end-of-line character (either \x0a or \x0d) was received, so the receive buffer contains a complete data transmission (less the EOL character, which is truncated) from the data source.

1

In line mode, the receive buffer received more data than it could hold, so the data received is not (necessarily) a complete transmission from the data source.

2

In character mode, the receive buffer received one character (or, depending on the incoming data rate, possibly more than one character).

See the stdinMode() function definition for a clarification of the difference between line mode and character mode.

Warning

Calling getInfo(18) from someplace other than a function hooked to HOOK_STDIN provides an undefined return value.

Remaining Tiny Strings

New in version SNAP 2.6.

Indicates how many “tiny” string buffers remain unused in your node. The size and number of tiny strings available on your node will vary depending on the underlying hardware and firmware.

Remaining Large Strings

New in version SNAP 2.6.

Indicates how many “large” string buffers remain unused in your node. The size and number of large strings available on your node will vary depending on the underlying hardware and firmware.

Script First Run

New in version SNAP 2.6.

Indicates whether the node has been rebooted since the last time a script was loaded onto it. Possible return values for getInfo(21):

Value

Meaning

0

There is no script on the node (either because it was empty when booted or because the script has been erased), or the node was rebooted since the script was loaded onto it.

1

The script has not been rebooted since the script was loaded onto it.
Script Base Address

New in version SNAP 2.6.

Indicates the base address for where the script resides in Flash.

Script Base Bank

New in version SNAP 2.6.

Indicates the base bank (zero-based) for where the script resides in Flash. For example, ATmega128RFA1’s Flash has two banks of 64K each and the SNAPpy script, by default, is located in the lower 64K bank. Therefore, getInfo(23) will return zero when called.

Is Directed Multicast

New in version SNAP 2.6.

Similar to getInfo(10), this indicates how the RPC command currently being processed was invoked and distinguishes between multicast and directed multicast. Possible return values for getInfo(24):

Value

Meaning

0

Received via an addressed RPC command, a multicast command, or was triggered by a system hook

1

Received via a directed multicast
Read and Reset Delay Factor

New in version SNAP 2.6.

Indicates the staggered delay (in milliseconds) that should be applied before targeted nodes make any reply to the directed multicast, giving nodes an opportunity to respond in sequence, without interfering with each other’s communications. See the description of the delayFactor parameter in the dmcastRpc() description for more information.

Invoking getInfo(25) clears the value, but also removes the staggered delay, putting the responsibility for avoiding communication collisions back in your hands. (There would be little reason to check this value without an intent to implement your own scheme to control communication timing.)

Warning

If called outside the context of a directed multicast, the return value is undefined.

Address Index

New in version SNAP 2.6.

Directed multicasts can target zero or more individual nodes by concatenating multiple addresses into the dstAddrs parameter. This indicates the (zero-based) position of this node’s address in a directed multicast address list.

Warning

The value is only meaningful in the context of a directed multicast call that specifically targets multiple nodes. In any other context (an addressed RPC, a regular multicast, or a directed multicast with an empty string for the target list) the return value is undefined.

Multicast Groups

New in version SNAP 2.6.

Indicates the multicast group mask specified for the call to the function being run. This is valid for both multicasts and directed multicasts. If the function is invoked with an addressed RPC call, this will return zero.

See mcastRpc() for more information about multicast groups.

Original TTL

New in version SNAP 2.6.

Indicates the value set for the ttl parameter on the dmcastRpc() call that invoked the running function. Note that this value is different from the Remaining TTL value, which provides the TTL remaining when the receiving node gets the message.

Warning

If called outside the context of a directed multicast, the return value is undefined.

C Compiler ID

New in version SNAP 2.7.

Indicates a unique identifier for the compiler version used to create any C code that has been compiled into the current SNAPpy script image. This has little practical value for the user at runtime, but it may be valuable in troubleshooting failures in scripts that include C code.

Build ID

New in version SNAP 2.7.

Indicates a unique identifier for the firmware build in your node, combining the firmware compilation date, Module Family, Build, Version (major, minor, and build), and Encryption into one hashed value. This has little practical value for the user at runtime, but it is used by SNAP to ensure that a script containing compiled C code was appropriately created for the firmware on which it is being asked to run.

getLq

getLq()

Get the most recent link quality (received signal strength) of the most recently received packet, regardless of which node that packet came from. Remember that the last packet could have come from a node that is close by or one that is far away.

Returns

A number in the range 0-127 (theoretical), representing the link quality in (-) dBm.

Return type

int

Note

Because this value represents (-) dBm, lower values represent stronger signals, and higher values represent weaker signals.

getMs

getMs()

Get the value of a free-running counter within the SNAP Engine representing elapsed milliseconds since startup. Since the counter is only 16 bits, it rolls over every 65.536 seconds. Because all SNAPpy integers are signed, the counter’s full cycle is:

0, 1, 2, ..., 32766, 32767, -32768, -32767, -32766, ..., -3, -2, -1, 0, 1, ...

Some scripts use this function to measure elapsed (relative) times. The value for this function is only updated between script invocations (events), meaning that you will get the same value no matter how many times you call getMs() during the same event.

Returns

16 bit count of milliseconds since startup.

Return type

int

getNetId

getNetId()

Get the current Network Identifier (ID).

The node will only accept packets containing this ID, or a special wildcard value of 0xffff which is used during the “find nodes” process.

The Network ID and the 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.

Returns

The node’s current Network ID.

Return type

int

See also

getStat

getStat(whichStat)

This function returns details about how busy the node has been with processing packets. Each return value ranges from 0 to 255. The values “peg” at 255 (i.e., once reaching 255 they stay there until cleared). Reading a value resets the counter to 0.

Parameters

whichStat (int) –

Specifies the counter to be retrieved.

Value

Counter Name

What is being counted?

0

Null Transmit Buffers

Buffers transmitted via a null serial port

1

UART0 Receive Buffers

Buffers received via UART0

2

UART0 Transmit Buffers

Buffers transmitted via UART0

3

UART1 Receive Buffers

Buffers received via UART1

4

UART1 Transmit Buffers

Buffers transmitted via UART1

5

Transparent Receive Buffers

Buffers received via transparent serial mode

6

Transparent Transmit Buffers

Buffers transmitted via transparent serial mode

7

Packet Serial Receive Buffers

Buffers received via packet serial mode

8

Packet Serial Transmit Buffers

Buffers transmitted via packet serial mode

9

Radio Receive Buffers

Buffers received via the radio

10

Radio Transmit Buffers

Buffers transmitted via the radio

11

Radio Forwarded Unicasts

Unicasts forwarded to nodes via the radio

12

Packet Serial Forwarded Unicasts

Unicasts forwarded to nodes via packet serial

13

Radio Forwarded Multicasts

Multicasts forwarded to nodes via the radio

14

Packet Serial Forwarded Multicasts

Multicasts forwarded to nodes via packet serial

Returns

Varies based on the value of whichStat.

Return type

int

i2cInit

i2cInit(enablePullups, SCL_pin, SDA_pin)

Performs the necessary setup for the I2C bus, including enabling internal pull-up resistors and optionally re-assigning the SCL and SDA I2C pins to another pair of SNAPpy IO pins.

The I2C clock and data lines require pull-ups. You can either choose to use your own external hardware or rely on the built-in internal ones. The internal pull-up resistors can come in handy when you are doing quick prototyping by dangling I2C devices directly off the SNAP Engine.

Parameters

  • enablePullups (bool) – Internal pull-up resistors are enabled when True; disabled when False.

  • SCL_pin (Optional[int]) – Specifies which SNAPpy IO pin to be used for SCL.

  • SDA_pin (Optional[int]) – Specifies which SNAPpy IO pin to be used for SDA.

Returns

None

Warning

Be careful not to “double pull-up” the I2C bus!

See also

i2cRead

i2cRead(byteStr, numToRead, retries, ignoreFirstAck)

Since I2C devices must be addressed before data can be read out of them, this function performs a write followed by a read.

Parameters

  • byteStr (str) – Specifies whatever “addressing” bytes must be sent to the device to get it to respond.

  • numToRead (int) – Specifies how many bytes to read back from the external I2C device.

  • retries (int) – Controls a spin-lock count used to give slow devices extra time to respond. Try an initial value of 1 and increase if needed.

  • ignoreFirstAck (bool) – True for devices that do not send an initial “ack” response, which will prevent an I2C error based on lack of an initial acknowledgement; False otherwise.

Returns

Bytes read from the external I2C device.

Return type

str

Note

This function can only be used after function i2cInit() has been called.

See also

  • User Guide on I2C

i2cWrite

i2cWrite(byteStr, retries, ignoreFirstAck, endWithRestart=False)

Writes a byte string to the I2C bus.

Parameters

  • byteStr (str) – Specifies the data to be sent to the external I2C device, including whatever “addressing” bytes must be sent to the device to get it to pay attention.

  • retries (int) – Controls a spin-lock count used to give slow devices extra time to respond. Try an initial value of 1 and increase if needed.

  • ignoreFirstAck (bool) – True for devices that do not send an initial “ack” response, which will prevent an I2C error based on lack of an initial acknowledgement; False otherwise.

  • endWithRestart (Optional[bool]) – True for devices that expect an I2C restart between I2C commands; False for devices that expect an I2C Start - Stop handshake sequence. Default is False. This argument was added in SNAP 2.5.

Returns

Number of bytes actually written.

Return type

int

Note

This function can only be used after function i2cInit() has been called.

See also

  • User Guide on I2C

imageName

imageName()

A SNAPpy script (.py file) gets compiled into a byte-code SNAPpy image (.spy file) using either SNAPbuild or Portal. The SNAPpy image name is assigned during this process from the underlying SNAPpy script. For example, image foo.spy would be generated from a script named foo.py. In this case, imageName() would return the string foo, even if someone had renamed the foo.spy file to a different name before loading it.

Returns

Name of currently loaded SNAPpy image.

Return type

str

Note

This returns the SNAPpy image that gets downloaded into the node, not the original (textual) source code.

initUart

initUart(uart, bps, dataBits=8, parity='N', stopBits=1)

Programs the specified UART to the specified bits per second (bps), or baud rate. Optionally, the data bits, parity, and stop bits can also be set.

Flow control defaults to the setting specified in NV11 - Feature Bits, typically it’s ‘On’. Use the flowControl() function to specify a setting.

Parameters

  • uartNum (int) – The specified UART, 0 or 1.

  • bps (int) – Usually set to the desired bits per second (1200, 2400, 9600, etc.); however, a value of 1 selects 115,200 bps (this large number would not fit into a SNAPpy integer and was treated as a special case). A value of 0 disables the UART.

  • dataBits (Optional[int]) – 7 or 8. (Default is 8.)

  • parity (Optional[str]) – ‘E’, ‘O’ or ‘N’, representing EVEN, ODD, or NO parity. (Default is ‘N’.)

  • stopBits (Optional[int]) – Number of stop bits. (Default is 1.)

Returns

None

Note

You are not limited to “standard” baud rates. If you need 1234 bps, you are allowed to do that.

See also

initVm

initVm()

Calling this function restarts the SNAPpy virtual machine. It will clear all globals you may have changed in your SNAPpy code back to their initially declared values, and it will cause all static or global variables declared in C code in SNAP 2.7 or newer to be reinitialized. It does not, however, reinvoke the SNAPpy script’s “startup” handler (the function hooked to the HOOK_START event).

This function is normally only used by Portal and SNAPconnect at the end of the script upload process.

Returns

None

int

int(obj)

Converts the specified object (usually a string) into numeric form.

Parameters

obj – Object to transform into a number.

Returns

Numeric representation of obj.

Return type

int

Examples

int('123')      # Returns 123
int(True)   # Returns 1
int(False)  # Returns 0

Note

Unlike regular Python, the SNAPpy int() function does not take an optional second parameter indicating the numeric base to be used. The obj to be converted to a numeric value is required to be in base 10 (decimal).

len

len(sequence)

This function returns the size of parameter sequence. This will be an element count for a tuple or the number of characters in a string.

Parameters

sequence – Must be a string or a tuple.

Returns

Number of items in sequence.

Return type

int

Examples

len('ABC') # Returns 3

loadNvParam

loadNvParam(id)

This function reads a single parameter from the SNAP node’s NV storage and returns it to the caller. For a full list of all the system (reserved) id values, refer to section 3. User parameters should have id values in the range 128-254.

Parameters

id (int) – Specifies which NV parameter to read.

Returns

Depends on the NV parameter.

See also

localAddr

localAddr()

Get the node’s local network address on the SNAP network.

Tracking what is essentially a six-digit (hexadecimal) number as a three-character string means that representations of the SNAP address may not appear meaningful when displayed. For example, if you were to use Portal to invoke localAddr() on a node with a a SNAP address of 5D.E3.AB, Portal’s Event Log would display the return value as ]ã«. If you were to display ord("]") or ord(localAddr()[0]) you would get 93, which is the decimal equivalent of hex 0x5D. Similarly, ord("ã") yields 227, which is the decimal equivalent of 0xE3, and ord("«") yields 171, which is the decimal equivalent of 0xAB. You could build this string directly as \x5d\xe3\xab.

This string representation of numbers as their separate character strings is a fundamental part of specifying addresses of nodes for SNAP communications.

Returns

String representation of the node’s 3-byte address on the SNAP network.

Return type

str

mcastRpc

mcastRpc(dstGroups, ttl, remoteFunction, *remoteFunctionArgs)

Make a remote procedure call (RPC) using multicast messaging, meaning this message could be acted upon by multiple SNAP nodes.

Parameters

  • dstGroups (str) – Specifies which nodes should respond to the request.

  • ttl (int) – Specifies the Time To Live (TTL) for the request, which is basically how many hops the message is allowed to make before being discarded.

  • remoteFunction (str) – Specifies which function to invoke on the remote node.

  • *remoteFunctionArgs (arbitrary argument list) – Used if the remote function takes any parameters.

Returns

This function normally returns True; however, it does not mean your RPC request was successfully sent and received.

It returns False only if it was unable to attempt the Remote Procedure Call (for example, if the node is low on memory or the RPC was too large to send).

Return type

bool

See also

mcastSerial

mcastSerial(dstGroups, ttl)

Set serial transparent mode to multicast.

Parameters

  • dstGroups (int) – Specifies the multicast groups that are eligible to receive this data.

  • ttl (int) – Specifies the maximum number of hops the data will be re-transmitted.

Returns

None

Warning

Multicast serial transparent mode is less reliable than unicast serial transparent mode, because the received serial characters will be sent using unacknowledged multicast messages.

See also

monitorPin

monitorPin(pin, isMonitored)

Enable background monitoring of a digital input pin’s level.

When a SNAPpy IO pin changes state, a HOOK_GPIN event is sent to the SNAPpy virtual machine. If you have assigned a HOOK_GPIN handler, it will be invoked with the number of the SNAPpy IO pin that changed state and the pin’s new value.

Parameters

  • pin (int) – Specifies which SNAPpy IO pin to monitor.

  • isMonitored (bool) – Enables monitoring when True, and disables monitoring when False.

Returns

None

Note

This SNAPpy IO pin must first be configured as a digital input pin using setPinDir().

See also

ord

ord(str)

Given a one-character string, this returns an integer of the ASCII for that character.

Parameters

str (str) – Specifies a single-character string to be converted.

Returns

Integer value of the ASCII character str.

Return type

int

Examples

::

The result of ord(‘A’) is 65 (0x41). The result of ord(‘2’) is 50 (0x32).

peek

peek(addr)

Read a byte from a specific memory location.

Parameters

addr (int) – Specifies which memory location to read (0-0x7FFF). A negative address will read a byte from internal EEPROM (-1 to -4096)

Returns

This returns the memory contents of the specified memory address

Return type

int

See also

  • poke() for writing the contents of a specific memory address

poke

poke(addr, byteVal)

Write the value of a specific memory location.

Parameters

  • addr (int) – Specifies which memory location to write (0-0x7FFF). A negative address will write a byte to internal EEPROM (-1 to -4096)

  • byteVal (int) – Specifies the data value which will be written to the specified memory address

Returns

None

See also

  • peek() for reading the contents of a specific memory address

pulsePin

pulsePin(pin, msWidth, isPositive)

Apply a pulse with a specified duration to a digital output pin.

The pulsePin() function behaves differently based on the value of msWidth:

  • Specifying a positive value for msWidth will generate a non-blocking pulse, meaning your SNAPpy script continues to run in parallel. This also allows you to have multiple pulses in progress at the same time. In this case, msWidth specifies the desired pulse width in milliseconds (1-32767).

  • Specifying a negative value for msWidth makes the pulse generation blocking, meaning the pulse runs to completion, and then your SNAPpy script resumes execution at the next line of code. In this case, the value of msWidth is platform-specific, but the desired pulse width is typically in microseconds. As a quick example, a value of -10000 on a Synapse RF200 would result in a pulse that is 10 milliseconds wide.

If you have multiple pulses on the same pin with the same isPositive setting, the first pulse to complete will set the pin to its final state, and the second pulse to complete will effectively have ended.

Parameters

  • pin (int) – Specifies which SNAPpy IO pin to pulse.

  • msWidth (int) – Specifies the desired pulse width and determines if the function will return immediately or wait until the pulse is complete. Specifying a value of 0 will result in no pulse at all.

  • isPositive (bool) – Controls the polarity of the pulse.

Returns

None

Note

This SNAPpy IO pin must first be configured as a digital output pin using setPinDir().

Warning

The timing of the pulsePin() function is not guaranteed to be precise. Pulses begin when the function invokes and end at a tick of the node’s internal clock. If you were to initiate a 1 ms pulse very shortly before the node’s next millisecond tick, the pulse would would be notably shorter than the 1 ms specified.

See also

random

random()

Returns a pseudo-random number.

Returns

A number between 0-4095.

Return type

int

readAdc

readAdc(channel)

Sample ADC on the specified analog input channel.

Some channels correspond to external analog input pins, the internal low voltage reference, or the internal high voltage reference. On some platforms, these can also return specialty readings such as processor temperature or voltage differences.

Parameters

channel (int) – Specifies which analog input channel to read.

Returns

Value of the specified analog input channel.

Return type

int

See also

readPin

readPin(pin)

Reads the current level of either a digital input or digital output pin.

Parameters

pin (int) – Specifies which SNAPpy IO pin to read.

Returns

The current logic level of the specified pin. It returns a “live value” for an input pin or the last value written for an output pin.

Return type

bool

Note

This SNAPpy IO pin must first be configured as a digital input or output pin using setPinDir().

See also

reboot

reboot(delay=200)

Reboot the node after an optional delay.

Providing for a delay allows the node time to acknowledge the reboot() request (in case it came in over-the-air). The delay parameter is treated as an unsigned integer. Sending 0xEA60 provides 60,000 ms, or one minute, of delay, as negative values (-5,536 in this case) are not meaningful.

The delay parameter is available beginning in SNAP 2.6.

Parameters

delay (Optional[int]) – Specifies when the reboot is to occur, in milliseconds. (Default is 200.) New in SNAP 2.6.

Returns

None

Note

Once a reboot is issued, scheduling a reboot later than an already running countdown will have no effect. However, issuing a reboot with a shorter duration than the current countdown will work.

resetVm

resetVm()

Reset the SNAPpy virtual machine ,which halts the currently running script. Even though the script is halted, it remains loaded in the node.

Returns

None

Note

Synapse tools like Portal and SNAPconnect use this in the script upload process.

See also

rpc

rpc(nodeAddress, remoteFunction, *remoteFunctionArgs)

Request that another SNAP node execute a function.

Parameters

  • nodeAddress (str) – Specifies the SNAP address of the target node.

  • remoteFunction (str) – Specifies which function to invoke on the remote node.

  • *remoteFunctionArgs (arbitrary argument list) – Used if the remote function takes any parameters.

Returns

This function normally returns True; however, it does not mean your RPC request was successfully sent and received.

It returns False only if it was unable to attempt the Remote Procedure Call (for example, if the node is low on memory or the RPC was too large to send).

Return type

bool

See also

rpcSourceAddr

rpcSourceAddr()

If a function on a node is invoked remotely (via RPC), then the called function can invoke function rpcSourceAddr() to find out the network address of the node which initiated the call. (If you call this function when an RPC is not in progress, it just returns None.)

This function allows a node to respond (answer back) directly to other nodes. An example will make this clearer. Imagine node “A” is loaded with a script containing the following function definition:

def pong():
    print 'got a response!'

Now imagine node “B” is loaded with a script containing the following function:

def ping():
    rpc(rpcSourceAddr(),'pong')

Node A can invoke function “ping” on node B. It can do this with a direct RPC, but it has to know node B’s address to do so:

rpc(node_B_address_goes_here, 'ping')

Or, it can do it with a multicast RPC, assuming that node B’s group membership is set appropriately:

mcastRpc(1, 1, 'ping')

When node B receives the RPC request packet, it will invoke local function “ping”, which will generate the remote “pong” request. Notice that node B can respond to a “ping” request from any node.

All SNAP network addresses are three-byte strings. Please see the localAddr() function for a description of how SNAP addresses are specified and notated.

Returns:

See also

rx

rx(isEnabled)

This function allows you to power down the radio, extending battery life in applications that do not actually need the radio (or only need it intermittently).

The radio defaults to ON in SNAP nodes. If you invoke rx(False), the radio will be powered down. Invoking rx(True), or sending any data over the radio, will power the radio back up.

To be clear, a node can wake up its own radio by attempting to transmit. A node’s radio will not be woken up by transmissions from other nodes.

Parameters

isEnabled (bool) – Controls whether or not the radio is on.

Returns

None

Note

If you turn the radio off (using rx(False)), then you will not receive any more radio traffic!

saveNvParam

saveNvParam(id, obj, bitmask)

Save object to indexed non-volatile storage location.

Parameters

  • id (int) – Specifies which NV parameter to modify.

  • obj – The data to be saved. Depending on the NV parameter, the data type could be boolean, integer, string, byte list, or None.

  • bitmask (Optional [int]) – Specifies which bits in obj will update the NV parameter’s value. Omitting this argument will overwrite the previous value with obj. This argument should only be used with integer obj values. New in version SNAP 2.6.

Returns

A result code.

Return type

int

The possible return values are:

Value

Enumeration

0

NV_SUCCESS

1

NV_NOT_FOUND

2

NV_DEST_TOO_SMALL

3

NV_FULL

4

NV_BAD_LENGTH

5

NV_FAILURE

6

NV_BAD_TYPE

7

NV_LOW_POWER

Examples

Assume that NV11 - Feature Bits contains the value 0x001F, which indicates that there is a power amplifier and that both UARTs are enabled. The following command will enable the Packet CRC bit (0x0400):

saveNvParam(NV_FEATURE_BITS_ID, 0x0400)         # NV11 = 0x0400

However, it will also overwrite all the other feature bits, disabling the power amplifier and both UARTs in the process. Instead, you need to combine the bit values:

saveNvParam(NV_FEATURE_BITS_ID, 0x041F)         # NV11 = 0x041F

Beginning in SNAP 2.6, you can use the optional bitmask argument:

saveNvParam(NV_FEATURE_BITS_ID, 0x0400, 0x0400) # NV11 = 0x041F

Note

NV parameters 128-254 are user-defined, so your script can use these parameters however you want. All values except None consume flash space. If you plan to no longer use a user-defined NV parameter, setting it to None will regain the flash space.

See also

scanEnergy

scanEnergy()

The getEnergy() function returns the result of a brief radio energy detection scan, as an integer. Function scanEnergy() is an extension of getEnergy(). It essentially calls getEnergy() N times in a row, changing the frequency before each getEnergy() scan. Here, ‘N’ refers to the number of frequencies supported by the radio.

For 2.4 GHz radios, 16 frequencies are supported by the radios, each corresponding to one channel. For 900 MHz radios running FHSS (frequency hopping) firmware, the 16 channels cover 66 radio frequencies, with each channel making use of 25 of those frequencies. For 868 MHz radios, there are three frequencies used, regardless of the channel selected. See the getChannel() function explanation for more details about how each radio platform uses the various frequencies available to it.

The scanEnergy() function returns an N-byte string, where the first character corresponds to the “detected energy level” on frequency 0, the next character corresponds to channel 1, and so on. (For 900 MHz FHSS radios, SNAP does not make use of the first and last frequencies but returns them as part of the string for completeness.) Thus, ord(scanEnergy()[4]) would return the same integer that calling getEnergy() from channel 4 would return.

The units for the “detected energy level” are the same as that returned by getLq(). Refer to the documentation on that function for more info.

Returns:

setChannel

setChannel(channel, network_id)

Set the SNAP Channel, and optionally the SNAP Network ID, of the node.

Parameters

  • channel (int) – Specify which frequency (or range of frequencies) the device should use for its communications. Values are platform specific.

  • network_id (Optional[int]) – Specify the SNAP Network ID (0-0xFFFF); if excluded, the node’s SNAP Network ID will be unchanged. New in version SNAP 2.6.

Returns

None

Example

setChannel(7 ,0x0C70)  # set the SNAP Channel to 7 and the SNAP Network ID to 0x0C70

Warning

This function only changes the “live” settings, so the effect lasts until the next reboot or power cycle. Use saveNvParam() to persist these settings into the correct NV Parameter.

Note

channel values 0-15 correspond to 802.15.4 channel 11-26 on 802.15.4/2.4 GHz devices.

See also

setNetId

setNetId(netId)

Set the SNAP Network ID of the node.

The combination of network ID and 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. (Of course, they also must be transmitting in the same frequency band. 900 MHz radios set to a given channel cannot communicate over the air with 2.4 GHz radios set to the same channel.) Nodes communicating over a serial link pay no attention to the channel and network ID.

Parameters

netId (int) – Specify the SNAP Network ID (0-0xFFFF).

Returns

None

Note

  • 0xFFFF is considered a “wildcard” network ID (matches all nodes), and you normally should only use network IDs of 0-0xFFFE.

  • This function changes the “live” network ID setting, and the effect only lasts until the next reboot or power cycle, or until setNetId() is called again. You should also use saveNvParam() to save the “persisted” network ID setting in NV3 - Network ID, if you want the node to stay on that network ID after its next reboot.

See also

setPinDir

setPinDir(pin, isOutput)

Configures a SNAPpy IO pin as either a digital input or digital output.

Parameters

  • pin (int) – Specifies which SNAPpy IO pin to configure.

  • isOutput (bool) – Pin is output when True; input when False.

Returns

None

Note

  • Calling setPinDir with a pin that is in use by another peripheral (eg UART or ADC) will automatically disable it.

See also

setPinPullup

setPinPullup(pin, isEnabled)

Enables the internal pull-up resistor for an IO pin.

Parameters

  • pin (int) – Specifies which SNAPpy IO pin to configure.

  • isEnabled – Enables the SNAPpy IO pin’s internal pull-up when True; disables when False.

Returns

None

Note

  • A SNAPpy IO pin’s internal pull-up is disabled by default.

  • This SNAPpy IO pin must first be configured as a digital input pin using setPinDir().

See also

setPinSlew

setPinSlew(pin, isRateControl)

Enable slew rate-control (~30ns) for a digital output pin.

Parameters

  • pin (int) – Specifies which SNAPpy IO pin to configure.

  • isRateControl – Enables the SNAPpy IO pin’s slew rate-control when True; disables when False.

Returns

None

Note

  • A SNAPpy IO pin’s slew rate-control is disabled by default.

  • This SNAPpy IO pin must first be configured as a digital output pin using setPinDir().

See also

setRadioRate

setRadioRate(rate)

Set the data rate of the radio. Only nodes set to the same rate can talk to each other over the air! All radios on the same frequency range and set to rate 0 will be interoperable.

Parameters

rate (int) – 0 specifies the standard data rate for the platform. Other rate values are platform-specific.

Returns

None

Warning

The “encoding” for non-standard data rates may differ between radio manufacturers. This means that different radio hardware may not be interoperable, even if set to the same (non-standard) rate.

See also

setRate

setRate(rateNum)

Adjusts the background sampling rate of digital IO pins.

Parameters

rateNum (int) – Specifies the background sampling rate.

Returns

None

The possible values for rateNum:

Value

Rate

0

OFF

1

Every 100 ms

2

Every 10 ms

3

Every 1 ms

Note

  • The background sampling rate is every 100 milliseconds by default.

  • This function has no effect unless/until you are using the monitorPin() function.

See also

sleep

sleep(mode, ticks)

This function puts the radio and CPU on the SNAP node into a low-power mode for a specified number of ticks. This is used to extend battery life.

A ticks parameter of 0 can be used to sleep until an IO pin interrupt occurs (see script pinWakeup.py), but SNAPpy is smart enough to know if you have not enabled a wakeup pin and will ignore a sleep(mode, 0) if there is no wakeup possible. Note that on some platforms not all processor pins come out to module pins; it might be possible to specify a wake pin that is not accessible, thus locking your node into a sleeping state. If this happens, make a serial connection to the node and use Portal ‘s Erase SNAPpy Image… menu option to clear the script and start over.

Starting with version SNAP 2.2, a negative ticks parameter can be used to access alternate sleep timings.

Starting with version SNAP 2.4.24, for most platforms the sleep function returns the remaining number of ticks if the node has been woken by a pin interrupt rather than the sleep call timing out. If the complete timed sleep has occurred, or if the sleep was untimed, the function returns zero. For example if you were to invoke sleep(1, 60) on a node but woke the node with an interrupt after 20 seconds, the function would return 40.

Parameters

  • mode – Chooses from the available sleep modes. The number of modes available and their characteristics, such as resolution and accuracy, is platform-specific.

  • ticks –

Returns:

See also

spiInit

spiInit(clockPolarity, clockPhase, isMsbFirst, isFourWire)

Initializes the Serial Peripheral Interface (SPI) Bus for the SNAP node.

Parameters

  • clockPolarity (bool) – Specifies the level of the CLK pin between SPI exchanges. True specifies that the clock is high when idle, and False specifies that the clock is low when idle.

  • clockPhase (bool) – Specifies which clock edge the incoming data will be latched in. If you number clock edges from 1, then True specifies the even clock edges for incoming data, and False specifies the odd clock edges for incoming data.

  • isMsbFirst (bool) – Controls the order in which individual bits within each byte will be shifted out. Setting this parameter to True will make the 0x80 bit go out first, and setting this parameter to False will make the 0x01 bit go out first.

  • isFourWire (bool) – Select the variant of SPI you are connecting to: True is four-wire, and False is three-wire.

Returns

None

Note

These settings depends on the device to which you are interfacing.

See also

spiRead

spiRead(byteCount, bitsInLastByte=8)

Reads data from a three-wire SPI device.

Parameters

  • byteCount (int) – Specifies how many bytes to read.

  • bitsInLastByte (int) – Makes it possible to accommodate devices with data widths that are not multiples of 8 bits. Value should be equal to the data width of device modulo 8. (Default is 8.)

Returns

Bytes received from SPI.

Return type

str

Note

This function can only be used after function spiInit() has been called.

See also

spiWrite

spiWrite(byteStr, bitsInLastByte=8)

Writes data to a three or four-wire SPI device.

Parameters

  • byteStr (str) – Specifies the actual bytes to be shifted out.

  • bitsInLastByte (int) – Makes it possible to accommodate devices with data widths that are not multiples of 8 bits. Value should be equal to the data width of device modulo 8. (Default is 8.)

Returns

None

Note

This function can only be used after function spiInit() has been called.

See also

  • User Guide on SPI

  • spiXfer() - to write and read data simultaneously (four-wire SPI only)

spiXfer

spiXfer(byteStr, bitsInLastByte=8)

Bidirectional data transfer over a four-wire SPI device. As bits are being shifted out to the slave device on the MOSI pin, bits from the slave device on the MISO pin are simultaneously being shifted in.

Parameters

  • byteStr (str) – Specifies the actual bytes to be shifted out.

  • bitsInLastByte (int) – Makes it possible to accommodate devices with data widths that are not multiples of 8 bits. Value should be equal to the data width of device modulo 8. (Default is 8.)

Returns

Byte string consisting of the bits that were shifted in (as the bits specified by parameter byteStr were

shifted out).

Return type

str

Note

This function can only be used after function spiInit() has been called.

See also

stdinMode

stdinMode(mode, echo)

This function controls whether or not received characters are echoed back to the user and how serial data is presented to your SNAPpy script via the HOOK_STDIN handler.

You can choose between line mode or character mode:

Line Mode

Characters are buffered up until either a Carriage Return (CR) or Line Feed (LF) is received. The complete string is then passed to your SNAPpy script via the HOOK_STDIN handler. Either the CR or LF character can trigger the hand-off, so if your terminal (or terminal emulator) is automatically adding extra CR or LF characters, you will see additional empty strings ("") passed to your script. For example, the character sequence A B C CR LF (or \x41\x42\x43\x0d\x0a) looks like two lines of input to SNAPpy.

Character Mode

Characters are passed to your SNAPpy script as soon as they become available via the HOOK_STDIN handler. If characters are being received fast enough, it still is possible for your script to receive more than one character at a time; they are just not buffered waiting for a CR or LF.

Parameters

  • mode (int) – 0 for line mode; 1 for character mode.

  • echo (bool) – True will retransmit any received characters to the sender.

Returns

None

Note

While your node is in line mode, SNAP reserves one “medium” string buffer to accept incoming data from STDIN. If your script is heavy on string usage but does not make use of HOOK_STDIN, you can recover use of the medium string used by line mode by changing to character mode.

See also

str

str(obj)

Given an element, returns a string representation of the element.

Parameters

obj – Element to be transformed into a string.

Returns

String representation of the element.

Return type

str

Examples

str(True)    # returns 'True'
str(123)     # returns '123'
str('hello') # returns 'hello'

txPwr

txPwr(power)

The radio on the SNAP node defaults to the maximum power allowed. Function txPwr() lets you reduce the power level from this default maximum.

Parameter power specifies a transmit power level from 0-17, with 0 being the lowest power setting and 17 being the highest power setting. On some platforms, government regulations prevent the hardware from being usable above certain levels. On one of those platforms, setting the transmit power higher than allowed pegs the power output at the highest allowed amount, so there may be no practical difference between setting the power to 16 and setting it to 17, for example.

Parameters

power (int) – The TX power level, in the range 0-17.

Returns

None

See also

type

type(arg)

Given a single argument, it returns an integer indicating the data type of the argument.

This function does not distinguish between constant or dynamic variables, nor between user functions or SNAPpy built-in functions.

Parameters

arg – Object to inspect.

Returns

Integer indicating the type of the object passed to it.

Return type

int

The expected return values (different from that returned in Python) are:

0

None

1

Integer

2

String

3

Function

5

Boolean

6

Tuple

7

Iterator

8

Byte List

31

Unknown

Note

Typically, you will not be able to create variables of an unknown type. However, if you have a Byte List variable and you use the del keyword to delete the entire list, the variable will be left with contents of an unknown type. Removing all elements from a list does not set the variable to an unknown type. Only deleting the list itself will do that.

ucastSerial

ucastSerial(dstAddr)

Set serial transparent mode to unicast.

Parameters

dstAddr – Specifies the SNAP address of the destination node.

Returns

None

See also

uniConnect

uniConnect(dst, src)

Establishes a one-way connection between two SNAP data-sources.

Parameters

  • dst – SNAP data destination.

  • src – SNAP data source.

Returns

None

See also

vmStat

vmStat(statusCode, args)

This function is specialized for management applications like Portal and provides a range of control/callback functionality.

Parameters

  • statusCode (int) – Controls what actions will be taken and what data will be returned via tellVmStat().

  • args – Varies depending on the statusCode. See below for details.

Returns

This function does not return a value, but it causes a tellVmStat() call to be made to the node that requested the vmStat().

The currently supported statusCode values are:

0-3

RESERVED

Internal Use Only

4

VM_NVREAD

Read and return the specified NV parameter

5

VM_NAME

Returns NODE NAME if set, else IMAGE NAME, plus Link Quality

6

VM_VERSION

Returns software version number

7

VM_NET

Returns Network ID and Channel

8

VM_SPACE

Returns Total Image (script) Space Available

9

VM_SCAN

Scans all RF channels for energy

10

VM_INFO

Returns Image Name (script name) and Link Quality

11

VM_DATA_SPACE

Returns the amount of space available for a SNAPpy image in auxiliary memory (valid only for the Si1000-based SNAP modules RF300, RF301, SM300, SM301)

12

VM_TOPOLOGY

Returns a string providing a list of nodes with which the target node can directly communicate

After the “varying” args parameter comes a final optional argument that specifies a “reply window” (in seconds) to randomly reply within. This helps prevent communication interference if you send a vmStat() command to multiple nodes concurrently.

If you do not specify a “reply window” parameter (or specify zero), the nodes will respond as rapidly as they can (subject to network traffic, communication difficulties, etc.).

Some of these commands are multicast by Portal; the “reply window” provides a way to keep all of the nodes from trying to respond at once. Specifying a non-zero “reply window” tells the node to pick a random time within the next “reply window” seconds and wait until then to reply.

Return Value Format:

When a node receives a vmStat() call, it responds to the source node with a call to tellVmStat(word, data).

The least significant byte of word will be the originally requested statusCode. The most significant byte will vary depending on the statusCode and is the “hiByte” described below. The data value is the main return value and is also dependant on the statusCode. For example, if a vmStat(4, 15, 3) were called, the called node would, within 3 seconds, reply with tellVmStat(3844, {contents of NV parameter 15 on the node}). Note that the second parameter could be an integer, a string, a Boolean, or None.

The 3844 value that was returned as word equates to 0x0F04. The “hiByte” of this value, 0x0F, indicates which NV parameter was read. The “lowByte” of this value, 0x04, indicates that the returned value comes as a result of a VM_NVREAD call. If the value of the first returned parameter is greater than 10, the “lowByte” will always contain the calling code, while the significance of the “hiByte” will vary depending on what call was made.

VM_NVREAD

For VM_NVREAD, the args parameter is the ID of the NV parameter you want to read. (These are the same IDs used in the saveNvParam() and loadNvParam() functions. The “system” NV parameter IDs are given in section 3.) You can also optionally specify a “reply window.”

The reported values will be a “hiByte” of the NV parameter ID and a “data” of the actual NV parameter value.

VM_NAME

For VM_NAME, the only parameter is the optional reply window.

The reported “data” value will be a string name and a Link Quality reading.

VM_VERSION

For VM_VERSION, the only parameter is the optional reply window.

The reported “data” value will be a version number string.

VM_NET

For VM_NET, the only parameter is the optional reply window.

The reported values will be a “hiByte” containing the currently active channel, and a “data” value of the current Network ID.

VM_SPACE

For VM_SPACE, the only parameter is the optional reply window.

The reported “data” value will be the Total Image (script) Space Available.

VM_SCAN

For VM_SCAN, the only parameter is the optional reply window.

The reported “data” value will be a string containing the detected energy levels on all channels. This value is identical to the value returned by the scanEnergy() function. Note that each scan just represents one point in time. You will probably have to initiate multiple scans to determine which channels actually have SNAP nodes on them.

You can see this VM_SCAN function put to use in the Channel Analyzer feature of Portal.

VM_INFO

For VM_INFO, the only parameter is the optional reply window.

The reported values will be a “hiByte” of the current Link Quality and a “data” of the currently loaded script name (a string).

VM_DATA_SPACE

For VM_DATA_SPACE, the only parameter is the optional reply window.

The reported values will be a “hiByte” of the current Link Quality and a “data” of the space available in auxiliary memory for a SNAPpy script (an integer).

VM_TOPOLOGY

For VM_TOPOLOGY, the only parameter is the optional reply window.

The reported values will be a “hiByte” of the current Link Quality and a “data” of details about nodes with which the reporting node can directly communicate (a string). Each node with which the reporting node can directly communicate will be represented by a block of five characters: The first three will be the node’s address, the fourth will be the link quality with which the neighboring node heard the reporting node, and the fifth will be the link quality with which the reporting node heard the neighboring node reply. Thus data[0:3] would be the address of one node and data[5:8] would be the address of another node (assuming that the reporting node could communicate with two neighbors).

It is possible that one call to vmStat(12)() may result in multiple calls back to tellVmStat() from a given node if that node has many neighbors with which it can directly communicate. In dense networks, it may be necessary to include the “reply window” parameter in order to provide enough time for all nodes to respond.

This option for vmStat() was added in SNAP 2.6, and the reporting node must have version SNAP 2.6 (or later) firmware installed. However, neighboring nodes can have earlier firmware versions on them and still report correctly.

Note

Because of the callback() function, some of the vmStat() capabilities are redundant.

writePin

writePin(pin, isHigh)

Sets the current level of a digital output pin.

Parameters

  • pin (int) – Specifies which SNAPpy IO pin to configure.

  • isHigh (bool) – Sets the SNAPpy IO pin high when True; low when False.

Returns

None

Note

This SNAPpy IO pin must first be configured as a digital output pin using setPinDir().

See also

  • Refer to SNAP Modules for SNAPpy IO pin numbers

  • setPinSlew() - controls how quickly the pin will transition to a new value

xrange

xrange(args)

New in version SNAP 2.6.

Creates a sequence iterator.

Parameters

args – Given a single integer as an argument, returns an iterator that yields integers beginning with zero and stepping up to one less than the passed argument. Given two integers, it returns an iterator that yields integers beginning with the first argument and steps up to one less than the second argument. Given three integers, it returns an iterator that yields integers beginning with the first argument and steps toward (but stops just before reaching or passing) the second argument, stepping in increments of the third argument.

Returns

An iterable that can be stepped through using a for loop.

Examples

There are three ways the function can be called:

for i in xrange(3):
    print i, # Prints 012

for i in xrange(3, 6):
    print i, # Prints 345

for i in xrange(3, 9, 2):
    print i, # prints 357

Note

Remember that SNAPpy integers are 16-bit signed numbers. Unlike a while loop that continually increments a counter until the stop value is reached, xrange() will generate an iterable that yields no numbers if the start value is greater than the stop value, unless the step value is negative.