Hooks¶

SNAP hooks are events that can occur at runtime. This section lists the supported hooks, their meanings, their triggers, and their (callback) parameters.

HOOK_SNAPCOM_OPENED¶

hooks.HOOK_SNAPCOM_OPENED¶

SNAP communications have been established over a TCP/IP link.

Parameters:	connection_info (tuple) – The IP address and TCP/IP port of the other SNAPconnect instance being connected to. snap_address (string) – The three-byte SNAP address of the other node (Ex. “\x12\x34\x56”).

Triggered By

This event is triggered by the establishment of an inbound or outbound TCP/IP connection with another instance of SNAPconnect, meaning that the root cause of the event was either:

a call to accept_tcp() that allowed/enabled incoming TCP/IP connections; or
a call to connect_tcp() that created an outgoing TCP/IP connection.

Example

def on_sc_open(connection_info, snap_address):
    pass

Note

If you want to know your own SNAP address, use the local_addr() function.

HOOK_SNAPCOM_CLOSED¶

hooks.HOOK_SNAPCOM_CLOSED¶

SNAP communications have ended (or failed to ever get established) over a TCP/IP link.

Scenario 1 – connection could not be established:

Parameters:	connection_info (tuple) – The IP address and TCP port of the other SNAPconnect instance for the failed connection attempt. snap_address (string) – None.

Scenario 2 – an established connection was shut down (parameters should match those provided with the SNAPCOM_OPENED hook):

Parameters:	connection_info (tuple) – The IP address and TCP port of the other SNAPconnect instance. snap_address (string) – The three-byte SNAP address of the other node (Ex. “\x12\x34\x56”).

Triggered By

This event is triggered by the shutdown of an established TCP/IP connection or failure to establish a connection in the first place (for example, calling connect_tcp() with the IP address of a computer that is not running SNAPconnect).

Example

def on_sc_close(connection_info, snap_address):
    pass

HOOK_SERIAL_OPEN¶

hooks.HOOK_SERIAL_OPEN¶

Communications over a specific serial (USB or RS-232) interface have started.

Parameters:

Parameters:	serial_type – The type of the serial port, one of: `SERIAL_TYPE_RS232`, `SERIAL_TYPE_SNAPSTICK100`, `SERIAL_TYPE_SNAPSTICK200`. port – The port of specified serial_type that opened, as appropriate for your operating system. On Windows, port is a zero-based list (for example, specify 0 for COM1). On Linux, port will typically be a string (for example, `/dev/ttys1`). addr (string) – The three-byte address of the SNAP device attached to this serial port (Ex. “\x12\x34\x56”), or None if the address could not be retrieved for any reason.

serial_type – The type of the serial port, one of: SERIAL_TYPE_RS232, SERIAL_TYPE_SNAPSTICK100, SERIAL_TYPE_SNAPSTICK200.
port – The port of specified serial_type that opened, as appropriate for your operating system. On Windows, port is a zero-based list (for example, specify 0 for COM1). On Linux, port will typically be a string (for example, /dev/ttys1).
addr (string) – The three-byte address of the SNAP device attached to this serial port (Ex. “\x12\x34\x56”), or None if the address could not be retrieved for any reason.

Triggered By

This event will occur after every successful call to open_serial(). After open_serial() is called, SNAPconnect will attempt to retrieve the address of the device attached to the serial port. This event will trigger after the address has been retrieved or the retrieval attempt has timed out.

Because the serial connection is open immediately after the call to open_serial(), it is possible that packets may be received on the interface before the node address can be determined and the hook function is called.

Example

def on_serial_open(serial_type, port, addr):
    pass

HOOK_SERIAL_CLOSE¶

hooks.HOOK_SERIAL_CLOSE¶

Communications over a specific serial (USB or RS-232) interface have ended.

Parameters:	serial_type – The type of the serial port, one of: `SERIAL_TYPE_RS232`, `SERIAL_TYPE_SNAPSTICK100`, `SERIAL_TYPE_SNAPSTICK200`. port – The port of specified serial_type that closed, as appropriate for your operating system. On Windows, port is a zero-based list (for example, specify 0 for COM1). On Linux, port will typically be a string (for example, `/dev/ttys1`).

Triggered By

A HOOK_SERIAL_CLOSE event can be triggered by a call to close_serial() or (in the case of some removable USB devices) by the physical removal of the device from the computer SNAPconnect is running on. This event can only occur after a successful call to open_serial().

Example

def on_serial_close(serial_type, port):
    pass

HOOK_RPC_SENT¶

hooks.HOOK_RPC_SENT¶

A packet created previously by a call to rpc(), mcast_rpc(), or dmcast_rpc() has been sent or all retries were exhausted while attempting to send the packet.

Parameters:

Parameters:	packet_identifier – The identifier for which packet was sent. Note `packet_identifier` is the same identifier that was originally returned by the call to `rpc()`, `mcast_rpc()`, or `dmcast_rpc()`. For compatibility with embedded SNAP nodes, you can also recover this identifier immediately after sending an RPC using `get_info(9)`. transmit_success – True if SNAPconnect believes the packet has been transmitted successfully or False if SNAPconnect was unable to send the packet. A successful transmit does not indicate that the packet was able to reach the destination.

packet_identifier –
The identifier for which packet was sent.

Note

packet_identifier is the same identifier that was originally returned by the call to rpc(), mcast_rpc(), or dmcast_rpc(). For compatibility with embedded SNAP nodes, you can also recover this identifier immediately after sending an RPC using get_info(9).
transmit_success – True if SNAPconnect believes the packet has been transmitted successfully or False if SNAPconnect was unable to send the packet. A successful transmit does not indicate that the packet was able to reach the destination.

Receipt of a hooks.HOOK_RPC_SENT does not mean the packet made it all the way to the other node. This is not an end-to-end acknowledgement. If transmit_success is False, the packet has not been transmitted. But if transmit_success is True, that is no guarantee the destination node actually received the packet.

SNAP has no provisions for end-to-end acknowledgement at the protocol layer. Any such functionality must be implemented in your application. For example, have a node send a return RPC in response to a request RPC. Only when the originating node receives the response RPC can it be certain that the original request made it through.

Triggered By

This event fires after any RPC packet is sent, regardless of whether it was sent by your application code or automatically by SNAPconnect behind the scenes.

Example

def on_rpc_sent(packet_identifier, transmit_success):
    pass

HOOK_STDIN¶

hooks.HOOK_STDIN¶

A packet containing user data has been received. This could either be unicast data addressed specifically to this node, or it could be multicast data sent to any nodes within specified multicast group[s].

Parameters:	data – The actual data (payload) of the DATA MODE packet.

Triggered By

This event is ultimately triggered by some other node invoking data_mode() or mcast_data_mode(), if it is a SNAPconnect application. Alternatively, an embedded SNAP node (such as an RF220) could be forwarding data from a serial port by use of the ucastSerial() or mcastSerial() functions.

Example

def on_stdin_rx(data):
    pass

Hint

If you need to know who the data came from, use the rpc_source_addr() function.

HOOK_TRACEROUTE¶

hooks.HOOK_TRACEROUTE¶

A traceroute has been successfully completed.

Parameters:

Parameters:	node_addr (string) – The three-byte SNAP address of the node that was “traced” (Ex. “\x12\x34\x56”). round_trip_time – The round trip time for the traceroute packet, after it made it past the initial hop. Note The first hop is not counted in traceroutes, because when the feature was originally implemented it was decided to only track the over-the-air timing. Bottom line – the bridge node component of your `round_trip_time` will be reported as 0 milliseconds. For TCP connections, this could significantly under-report the speed of that first hop. hops – A Python list of tuples, with one list entry for every “hop” that the traceroute made on its journey to and from the target node. For example, a traceroute to your directly connected bridge node will have two hops – one for the hop from SNAPconnect to the bridge node, and a second hop back from the bridge node to SNAPconnect. Each Python tuple within the hops list will be made up of two values: hop[0] will be the SNAP address that the traceroute packet was received from. hop[1] will be the link quality at which the traceroute was received, if it was received over a radio link. (Serial links and TCP/IP links have no true “link quality” in SNAP, and will always be reported as having a LQ of 0.) The link quality is reported in (negative) dBm, so lower values represent stronger signals. The theoretical range for the link quality is 0-127.

node_addr (string) – The three-byte SNAP address of the node that was “traced” (Ex. “\x12\x34\x56”).
round_trip_time –
The round trip time for the traceroute packet, after it made it past the initial hop.

Note

The first hop is not counted in traceroutes, because when the feature was originally implemented it was decided to only track the over-the-air timing. Bottom line – the bridge node component of your round_trip_time will be reported as 0 milliseconds. For TCP connections, this could significantly under-report the speed of that first hop.
hops –
A Python list of tuples, with one list entry for every “hop” that the traceroute made on its journey to and from the target node.

For example, a traceroute to your directly connected bridge node will have two hops – one for the hop from SNAPconnect to the bridge node, and a second hop back from the bridge node to SNAPconnect.
Each Python tuple within the hops list will be made up of two values:
- hop[0] will be the SNAP address that the traceroute packet was received from.
- hop[1] will be the link quality at which the traceroute was received, if it was received over a radio link. (Serial links and TCP/IP links have no true “link quality” in SNAP, and will always be reported as having a LQ of 0.) The link quality is reported in (negative) dBm, so lower values represent stronger signals. The theoretical range for the link quality is 0-127.

Triggered By

This event is triggered by invoking the traceroute() function for a node that is actually reachable and can respond.

Example

def on_traceroute_done(node_addr, round_trip_time, hops):
    pass

HOOK_OTA_UPGRADE_COMPLETE¶

hooks.HOOK_OTA_UPGRADE_COMPLETE¶

An over-the-air firmware upgrade has completed.

Parameters:	upgrade_addr (string) – The three-byte SNAP address of the node for which the upgrade has completed (Ex. “\x12\x34\x56”). status_code – The result of the upgrade. See the Firmware upgrades section for more details. message – A human-readable string describing the cause of an error, or None if the upgrade was successful.

Triggered By

This event follows a call to the upgrade_firmware() function. The event is triggered when an upgrade completes successfully or an error occurs that halts the upgrade progress.

Example

def on_ota_complete(upgrade_addr, status_code, message):
    pass

HOOK_OTA_UPGRADE_STATUS¶

hooks.HOOK_OTA_UPGRADE_STATUS¶

An over-the-air firmware upgrade status has advanced.

Parameters:	upgrade_addr (string) – The three-byte SNAP address of the node receiving the upgrade (Ex. “\x12\x34\x56”). percent_complete – An estimate (as a Python float) of how much of an upgrade has been completed, as a percentage.

Triggered By

This event follows a call to the upgrade_firmware() function. The event is triggered every time progress is made in an over-the-air upgrade and will be called many times for every upgrade started and not immediately stopped.

Example

def on_ota_status(upgrade_addr, percent_complete):
    pass

Authentication Realms

Exceptions