Functions

__init__

class SnapConnectFutures(snapconnect)

Wrap a SNAPconnect instance with the ability to return Futures.

Parameters:snapconnect (snap.Snap) – SNAPconnect instance to wrap

Example

from snapconnect_futures import SnapConnectFutures
from snapconnect import snap
from tornado.gen import coroutine
import apy
import tornado

# Required IO loop setup:
# Create an apy IOLoopScheduler
scheduler = apy.ioloop_scheduler.IOLoopScheduler.instance()

# Create a SNAPconnect instance that uses the apy scheduler
comm = snap.Snap(scheduler=scheduler, funcs={})

# Setup tornado's IO loop by scheduling calls to SNAPconnect's poll_internals method
tornado.ioloop.PeriodicCallback(comm.poll_internals, 5).start()

# Create an SCF instance using an existing SNAPconnect instance
# This registers all of our callbacks automatically:
scf = SnapConnectFutures(comm)

SnapConnectFuturesAuto

SnapConnectFuturesAuto(sc_license=None, sc_address=None, sc_scheduler=None)

If you are unfamiliar with SNAPconnect Futures, you may want to use this helper function to instantiate a SnapConnectFutures object with common defaults that abstracts away some of the necessary calls.

Parameters:
  • sc_license – SNAPconnect license to use
  • sc_address – SNAPconnect address to use (Ex: “aabbcc”)
  • sc_scheduler – apy scheduler to use
Returns:

An instance of SnapConnectFutures initialized with a simple configuration.

Example

from snapconnect_futures import SnapConnectFuturesAuto
from snapconnect import snap
from tornado.gen import coroutine
import tornado

scf = SnapConnectFuturesAuto()

callback_dmcast_rpc

SnapConnectFutures.callback_dmcast_rpc(*args, **kwargs)

Send a callback directed multicast RPC with automatic callback, timeout, and retry handling.

This waits for every address to respond. If we’re out of timeouts and retries, then it returns None.

Example:

"aabbcc": ("response1"), # This one responded with one argument
"bbccdd": (10, 20, 30), # This one responded with 3 arguments
"ddeeff": None,  # We didn't hear a response from this one
["aabb11", "bbcc22"]  # We couldn't fit these 2
Parameters:
  • addrs (str | list[str]) – List of SNAP addresses we expect to respond (Ex: [“aabbcc”, “ccddee”]). If blank/empty (‘’ or []), any responding node will be treated as if it were expected.
  • funcname (str) – Name of function to call with RPC
  • *args – Arguments to pass to the node
  • **kwargs – Keyword arguments for SNAPconnect. View Keyword Arguments for specific kwargs expected.
Keyword Arguments:
 
  • callback_name (str) – If None, send the RPC with ‘callback’ to an automatically assigned callback value. If set to a value, listen for an automatic response from the RPC with the given value. Default : None
  • dmcast_delay (int) – Millisecond delay between dmcast responses. If not provided or None, use default delay. Default : None
  • expect_seq (bool) – True if a sequence number will be appended to the RPC args. Used in most lighting RPCs. Default : False
  • group (int) – Multicast Group. If not provided or None, use default group. Default : None
  • node_limit (int | None) – The max number of nodes allowed in a dmcast. None if we should fit as many as possible. Default : None
  • result_type (namedtuple) – Named tuple describing the format of the returned value. Default : None
  • retries (int) – Number of times to retry the message after a timeout. Default : 3
  • timeout (float) – Number of seconds to wait before timing out. Default : 2
  • ttl (int) – Number of hops. If not provided or None, use default ttl. Default : None
  • validate_func (function) – The function to apply to each result of the callback. This function should take one RPC response tuple and return True or False.
Raises:

TypeError – Raised if an invalid keyword argument is provided.

Returns:

A future that resolves to the return value of the functions as a dictionary. None if we don’t get a result.

Return type:

Future | None

Other Parameters:
 
  • chunk_results (bool) – (Internal Use Only) If True, return the results in chunks with unprocessed nodes. If False, run until we have every single result and then return. Default : False
  • previous_chunk (MultiResult) – (Internal Use Only) Used to continue processing data when chunk_results is set to True. Used internally when chunk_results is set to True. Default : None

Note

  • callback_dmcast_rpc uses get_defalt_dmcast_delay() to obtain the default dmcast delay unless overridden via kwards
  • callback_dmcast_rpc uses get_default_mcast_group() to obtain the default mcast group unless overridden via kwargs
  • callback_dmcast_rpc uses get_default_mcast_ttl() to obtain the default mcast ttl unless overridden via kwargs

callback_mcast_rpc

SnapConnectFutures.callback_mcast_rpc(addrs, funcname, *args, **kwargs)

Send a callback multicast RPC with automatic callback, timeout, and retry handling.

This waits for every address to respond. If we’re out of timeouts and retries, then it returns None.

Parameters:
  • addrs (str | list[str]) – Single SNAP address or list of SNAP addresses we expect to respond (Ex: [“aabbcc”, “ccddee”]). If blank/empty (‘’ or []), any responding node will be treated as if it were expected.
  • funcname (str) – Name of function to call with RPC
  • *args – Arguments to pass to the node
  • **kwargs – Keyword arguments for SNAPconnect. View Keyword Arguments for specific kwargs expected.
Keyword Arguments:
 
  • callback_name (str) – If None, send the RPC with ‘callback’ to an automatically assigned callback value. If set to a value, listen for an automatic response from the RPC with the given value. Default : None
  • group (int) – Multicast Group. If not provided or None, use default group. Default : None
  • result_type (namedtuple) – Named tuple describing the format of the returned value. Default : None
  • retries (int) – Number of times to retry the message after a timeout. Default : 3
  • timeout (float) – Number of seconds to wait before timing out. Default : 2
  • ttl (int) – Number of hops. If not provided or None, use default ttl. Default : None
  • validate_func (function) – The function to apply to each result of the callback. This function should take one RPC response tuple and return True or False.
Raises:

TypeError – Raised if an invalid keyword argument is provided.

Returns:

A future that resolves to the return value of the functions as a dictionary. None if we don’t get a result.

Return type:

Future | None

Note

callback_rpc

SnapConnectFutures.callback_rpc(addr, funcname, *args, **kwargs)

Send a callback RPC with automatic callback, timeout, and retry handling.

Parameters:
  • addr (str) – SNAP address (Ex: “aabbcc”)
  • funcname (str) – Name of function to call with RPC
  • *args – Arguments to pass to the node
  • **kwargs – Keyword arguments for SNAPconnect. View Keyword Arguments for specific kwargs expected.
Keyword Arguments:
 
  • callback_name (str) – If None, send the RPC with ‘callback’ to an automatically assigned callback value. If set to a value, listen for an automatic response from the RPC with the given value. Default : None
  • result_type (namedtuple) – Named tuple describing the format of the returned value. Default : None
  • retries (int) – Number of times to retry the message after a timeout. Default : 3
  • timeout (float) – Number of seconds to wait before timing out. Default : 2
  • validate_func (function) – The function to apply to each result of the callback. This function should take one RPC response tuple and return True or False.
Raises:

TypeError – Raised if an invalid keyword argument is provided.

Returns:

A future that resolves to the return value of the function or None if we don’t get a result

Return type:

Future | None

close_serial

SnapConnectFutures.close_serial(serial_type, port, timeout=2)

Return a future that resolves to True when a serial connection is closed

Parameters:
  • serial_type (int) – The type of serial interface to close
  • port (int | str) – Port to close for the given serial type
  • timeout (float) – Time in seconds before the close has failed
Raises:

TimeoutError – Serial connection did not close before timeout.

Returns:

A future that resolves to True when a serial connection is closed

Return type:

Future

See also

dmcast_rpc

SnapConnectFutures.dmcast_rpc(addrs, funcname, *args, **kwargs)

Send a directed multicast RPC with no retry, timeout, or callback handling.

Parameters:
  • addrs (str | list[str]) – List of SNAP addresses (Ex: [“aabbcc”, “ccddee”])
  • funcname (str) – Function to call
  • *args – Arguments for RPC
  • **kwargs – Keyword arguments for SNAPconnect. View Keyword Arguments for specific kwargs expected.
Keyword Arguments:
 
  • delay (int) – Millisecond delay between dmcast responses. If not provided or None, use default delay. Default: None
  • group (int) – Multicast Group. If not provided or None, use default group. Default: None
  • ttl (int) – Number of hops. If not provided or None, use default ttl. Default: None
Returns:

Resolves to True if SNAPconnect believes the packet was sent. Resolves to False, otherwise.

Return type:

Future

Example

dmcast_rpc_success = yield scf.dmcast_rpc(["aabbcc", "ccddee"], "test_func", "arg1", "arg2")
# => True

Note

get_addr_str

static SnapConnectFutures.get_addr_str(addrs)

Return a list of hexlified addresses for RPCs.

Parameters:addrs (str | list[str]) – List of one or more unhexlifed addresses. Ex: [“aabbcc”, “112233”]
Raises:TypeError – If an invalid address is provided
Returns:Comma-separated str of provided addresses

get_default_dmcast_delay

static SnapConnectFutures.get_default_dmcast_delay()

Return the default directed multicast delay. Override in a subclass if your application changes this dynamically.

Returns:Default directed multicast delay

get_default_mcast_group

static SnapConnectFutures.get_default_mcast_group()

Return the default multicast group. Override in a subclass if your application changes this dynamically.

Returns:Default multicast group

get_default_mcast_ttl

static SnapConnectFutures.get_default_mcast_ttl()

Return the default multicast TTL. Override in a subclass if your application changes this dynamically.

Returns:Default multicast TTL

get_results_with_result_type

static SnapConnectFutures.get_results_with_result_type(result_type, callback_result)

Return the responses that match a result type.

Parameters:
  • result_type (namedtuple) – The type of callback expected
  • callback_result (dict[str, tuple]) – The result of the callback
Returns:

The converted results and the dict of invalid responses that were too long or too short

Return type:

tuple[dict, dict]

mcast_rpc

SnapConnectFutures.mcast_rpc(funcname, *args, **kwargs)

Send a multicast RPC with no retry, timeout, or callback handling.

Parameters:
  • funcname (str) – Function to call
  • *args – Arguments for RPC
  • **kwargs – Keyword arguments for SNAPconnect. View Keyword Arguments for specific kwargs expected.
Keyword Arguments:
 
  • group (int) – Multicast Group. If not provided or None, use the default group. Default: None
  • ttl (int) – Number of hops. If not provided or None, use the default ttl. Default: None
Returns:

Resolves to True if SNAPconnect believes the packet was sent. Resolves to False, otherwise.

Return type:

Future

Example

mcast_rpc_success = yield scf.mcast_rpc("test_func", "arg1", "arg2")

Note

open_serial

SnapConnectFutures.open_serial(serial_type, port, forward_groups=None, baudrate=None, timeout=2)

Return a future that resolves to the bridge address when a serial connection is opened.

Parameters:
  • serial_type (int) – The type of serial interface to open
  • port (int | str) – Port to connect to for the given serial type
  • forward_groups (int) – Multi-cast groups to forward through. Defaults to the NV parameter default.
  • baudrate (int) – The baudrate for the serial connection. Defaults to SNAPconnect’s default.
  • timeout (float) – Time in seconds before the open attempt has failed
Raises:

TimeoutError – Serial connection did not open before timeout.

Returns:

A future that resolves to the bridge address when a serial connection is opened.

Return type:

Future

See also

rpc

SnapConnectFutures.rpc(addr, funcname, *args)

Send a unicast RPC with no retry, timeout, or callback handling.

Parameters:
  • addr (str) – SNAP address (Ex: “aabbcc”)
  • funcname (str) – Function to call
  • *args – Arguments for RPC
Returns:

Resolves to True if SNAPconnect believes the packet was sent. Resolves to False, otherwise.

Return type:

Future

Example

rpc_success = yield scf.rpc("aabbcc", "test_func", "arg1", "arg2")
# => True

upgrade_firmware

SnapConnectFutures.upgrade_firmware(addr, sfi_file_path, timeout=60)

Return a future that resolves to True if the firmware upgrade was successful or False if it was not.

Parameters:
  • addr (str) – SNAP address (Ex: “aabbcc”)
  • sfi_file_path (str) – Full path to SNAP Firmware Image file
  • timeout (float) – Time in seconds before an upgrade has failed
Raises:

TimeoutError – Upgrade firmware doesn’t complete before timeout.

Returns:

A future that resolves to True if the firmware upgrade was successful or False if it was not.

Return type:

Future

upgrade_script

SnapConnectFutures.upgrade_script(addr, spy_file_path, timeout=60)

Return a future that resolves to True if the script upgrade was successful or False if it was not.

Parameters:
  • addr (str) – SNAP address (Ex: “aabbcc”)
  • spy_file_path (str) – Full path to SNAPpy SPY file
  • timeout (float) – Time in seconds before an upgrade has failed
Raises:

TimeoutError – Unable to open script before timeout.

Returns:

A future that resolves to True if the script upgrade was successful or False if it was not.

Return type:

Future