Node Classes

The WlanExpNode class represents one node in a network of nodes running the 802.11 Reference Design. This class is the primary interface for interacting with nodes by providing methods to send commands and read status of the node. This is the base class for all node types and provides the common functionality for all nodes.

Base Node Class

The WlanExpNode class implements the interface to an 802.11 Reference Design node. The WlanExpNode class should not be instantiated directly. Refer to the wlan_exp examples (http://warpproject.org/trac/wiki/802.11/wlan_exp/examples) for the recommend node initialization flow which returns a properly initialized WlanExpNode instance.

The class attributes listed below should be considered read-only. The relevant attributes are given values during the initialization process. These values represent the identity and state of the node running the 802.11 Reference Design. Changing an attribute value does not change the corresponding state of the node, a mismatch that will distrupt normal operation of wlan_exp tools.

class WlanExpNode(network_config=None)

Class for 802.11 Reference Design Experiments Framwork node.

Parameters:

network_config (transport.NetworkConfiguration) – Network configuration of the node

Variables:

• node_id (int) – Unique identification for this node
• name (str) – User specified name for this node (supplied by user scripts)
• description (str) – String description of this node (auto-generated)
• serial_number (int) – Node’s serial number, read from EEPROM on hardware
• fpga_dna (int) – Node’s FPGA’a unique identification (on select hardware)
• transport (transport.Transport) – Node’s transport object
• transport_broadcast (transport.Transport) – Node’s broadcast transport object
• wlan_mac_address (int) – Wireless MAC address of the node (inherited from WlanDevice)
• ht_capable (bool) – Indicates if device has PHY capable of HT (802.11n) rates (inherited from WlanDevice)
• scheduler_interval (int) – Minimum resolution (in usec) of the scheduler. This is also the minimum time between LTG events.
• log_max_size (int) – Maximum size of event log (in bytes)
• log_total_bytes_read (int) – Number of bytes read from the event log
• log_num_wraps (int) – Number of times the event log has wrapped
• log_next_read_index (int) – Index in to event log of next read
• wlan_exp_ver_major (int) – wlan_exp Major version running on this node
• wlan_exp_ver_minor (int) – wlan_exp Minor version running on this node
• wlan_exp_ver_revision (int) – wlan_exp Revision version running on this node
• max_tx_power_dbm (int) – Maximum transmit power of the node (in dBm)
• min_tx_power_dbm (int) – Minimum transmit power of the node (in dBm)

Node Sub-Classes

The AP, STA and IBSS node types are represented by dedicated subclasses of WlanExpNode. The node objects in wlan_exp scripts will be instances of these subclasses. Each subclass implements methods that are specific to a given node type.

• Access Point (AP) Node
• Station (STA) Node
• Ad hoc (IBSS) Node

Common Node Methods

The list below documents each node method implemented by the WlanExpNode class. These methods can be used with any wlan_exp node type (AP, STA, IBSS).

Node

These WlanExpNode commands are used to interact with the node and control parameters associated with the node operation.

WlanExpNode.reset_all()

Resets all portions of a node.

This includes:

• Log
• Counts
• Local Traffic Generators (LTGs)
• Wireless Tx Queues
• BSS (i.e. all network state)
• Observed Networks (network_info_list)
• Observed Stations (station_info_list)

See the reset() command for a list of all portions of the node that will be reset.

WlanExpNode.reset(log=False, txrx_counts=False, ltg=False, tx_queues=False, bss=False, network_list=False, station_info_list=False)

Resets the state of node depending on the attributes.

Parameters:

• log (bool) – Reset the log data. This will reset both the log data on the node as well as the local variables used to track log reads for log_get_all_new(). This will not alter any log settings set by log_configure().

• txrx_counts (bool) – Reset the TX/RX Counts. This will zero out all of the packet / byte counts as well as the latest_txrx_timestamp for all nodes in the station info list. It will also remove all promiscuous counts.

• ltg (bool) – Remove all LTGs. This will stop and remove any LTGs that are on the node.

• tx_queues (bool) – Purge all wireless Tx queues. This will discard all currently enqueued packets awaiting transmission at the time the command is received. This will not discard packets already submitted to the lower-level MAC for transmission.

• bss (bool) – Reset network state. This will nullify the node’s active BSS and removes all entries from the station info list. However, it will not remove the BSS from the network list. This will produce the following OTA transmissions:

  • For AP, a deauthentication frame to each associated station
  • For STA, a disassociation frame to its AP
  • For IBSS, nothing.

• network_list (bool) – Resets the list of observed wireless networks. This will not remove the network_info for the node’s current BSS.

• station_info_list (bool) – Resets the list of observed wireless clients. This will not remove station_info entries for any associated nodes.

WlanExpNode.get_wlan_mac_address()

Get the WLAN MAC Address of the node.

Returns:Wireless Medium Access Control (MAC) address of the node. Return type:MAC Address (int)

WlanExpNode.set_mac_time(time, time_id=None)

Sets the MAC time on the node.

Parameters:

• time (int) – Time to which the node’s MAC time will be set (int in microseconds)
• time_id (int, optional) – Identifier used as part of the TIME_INFO log entry created by this command. If not specified, then a random number will be used.

WlanExpNode.get_mac_time()

Gets the MAC time from the node.

Returns:Timestamp of the MAC time of the node in int microseconds Return type:time (int)

WlanExpNode.get_system_time()

Gets the system time from the node.

Returns:Timestamp of the System time of the node in int microseconds Return type:Time (int)

WlanExpNode.enable_beacon_mac_time_update(enable)

Enable / Disable MAC time update from received beacons.

Parameters:enable (bool) – True enables and False disables MAC time updates from received beacons

WlanExpNode.set_radio_channel(channel)

Re-tune the node’s RF interfaces to a new center frequency.

This method directly controls the RF hardware. This can be disruptive to MAC operation if the node is currently associated with other nodes in a BSS which manages its own channel state.

This method will immediately change the center frequency of the node’s RF interfaces. As a result this method can only be safely used on a node which is not currently a member of a BSS. To change the center frequency of nodes participating in a BSS use the node.configure_bss(channel=N) method on every node in the BSS.

Parameters:channel (int) – Channel index for new center frequency. Must be a valid channel index. See wlan_channels in util.py for the list of supported channel indexes.

WlanExpNode.set_low_to_high_rx_filter(mac_header=None, fcs=None)

Configures the filter that controls which received packets are passed from CPU Low to CPU High.

The filter will always pass received packets where the destination address matches the node’s MAC address. The filter can be configured to drop or pass other packets. This filter effectively controls which packets are written to the node’s log.

Parameters:

• mac_header (str, optional) – MAC header filter. Values can be:
  • 'MPDU_TO_ME' – Pass all unicast-to-me or multicast data or management packet
  • 'ALL_MPDU' – Pass all data and management packets; no destination address filter
  • 'ALL' – Pass all packets; no packet type or address filters
• fcs (str, optional) – FCS status filter. Values can be:
  • 'GOOD' – Pass only packets with good checksum result
  • 'ALL' – Pass packets with any checksum result

At boot the filter defaults to mac_header='ALL' and fcs='ALL'.

WlanExpNode.set_low_param(param_id, param_values)

Set a CPU Low parameter

This command provides a generic data pipe to set parameters in CPU Low. Currently supported parameters are defined in cmds.py and use the naming convention: CMD_PARAM_LOW_PARAM_* In some cases, additional commands have been added to the node that utilize set_low_param() in order to add error checking.

See http://warpproject.org/trac/wiki/802.11/wlan_exp/Extending for more information about how to extend set_low_param() to control additional parameters.

Parameters:

• param_id (int) – ID of parameter to be set
• param_values (list of int) – Value(s) to set the parameter

WlanExpNode.set_dcf_param(param_name, param_val)

Configures parameters of the DCF MAC in CPU Low.

These parameters are write-only. These parameters only affect nodes running the DCF in CPU Low. Other MAC implementations should ignore these parameter updates.

Parameters:

• param_name (str) – Name of the param to change (see table below)
• param_val (int) – Value to set for param_name (see table below)

This method currently implements the following parameters:

Name	Valid Values	Description
'rts_thresh'	[0 .. 65535]	Threshold in bytes for maximum length packet which will not trigger RTS handshake
'short_retry_limit' and 'long_retry_limit'	[0 .. 10]	DCF retry limits, controls maximum number of retransmissions for short and long packets See retransmissions. for more details.
'cw_exp_min' and 'cw_exp_max'	[0 .. 16]	Contention window exponent bounds. Contention window is set to random number in [0, (2^CW - 1)], where CW is bounded by [cw_exp_min, cw_exp_max]

WlanExpNode.configure_pkt_det_min_power(enable, power_level=None)

Configure Minimum Power Requirement of Packet Detector.

Parameters:

• enable (bool) – True/False
• power_level (int) – [-90,-30] dBm

WlanExpNode.set_phy_samp_rate(phy_samp_rate)

Sets the PHY sample rate (in MSps)

Parameters:phy_samp_rate (int) – PHY sample rate in MSps (10, 20, 40). Default is 20 MSps.

WlanExpNode.set_random_seed(high_seed=None, low_seed=None, gen_random=False)

Sets the random number generator seed on the node.

Parameters:

• high_seed (int, optional) – Set the random number generator seed on CPU high
• low_seed (int, optional) – Set the random number generator seed on CPU low
• gen_random (bool, optional) – If high_seed or low_seed is not provided, then generate a random seed for the generator.

WlanExpNode.enable_dsss(enable)

Enable / Disable DSSS receptions on the node

By default DSSS receptions are enabled on the node when possible (ie PHY sample rate is 20 MHz and Channel is in 2.4 GHz band)

Parameters:

enable (bool) –

• True - enable DSSS receptions on the node
• False - disable DSSS receptions on the node

WlanExpNode.set_print_level(level)

Set the verbosity of the wlan_exp output to the node’s UART.

Parameters:level (int) – Printing level (defaults to WARNING)

Valid print levels can be found in wlan_exp.util.uart_print_levels:

• NONE - Do not print messages
• ERROR - Only print error messages
• WARNING - Print error and warning messages
• INFO - Print error, warning and info messages
• DEBUG - Print error, warning, info and debug messages

WlanExpNode.enable_ethernet_portal(enable)

Enable / Disable Ethernet Portal opertion of the node. When the portal is enabled the node bridges its ETH A Ethernet connection to the wireless medium. When the portal is disabled the node ignores all packets on ETH A and will not send any Ethernet transmissions on ETH A.

The Ethernet portal is enabled by default. Disabling the portal with this command is “sticky” - the portal will remain disabled until explicity re-enabled or until the node is rebooted. Changes to BSS state will not affect whether the Ethernet portal is enabled or disabled.

Parameters:enable (bool) – True enables and False disables Ethernet portal functionality

WlanExpNode.queue_tx_data_purge_all()

WlanExpNode.send_user_command(cmd_id, args=None)

Send User defined command to the node

See documentation on how-to extend wlan_exp: http://warpproject.org/trac/wiki/802.11/wlan_exp/Extending

Parameters:

• cmd_id (u32) – User-defined Command ID
• args (u32, list of u32) – Scalar or list of u32 command arguments to send to the node

Returns:

List of u32 response arguments received from the node

Return type:

resp_args (list of u32)

WlanExpNode.identify()

Identify the node

The node will physically identify itself by:

• Blinking the Hex Display (for approx 10 seconds)
• Output Node ID and IP adress to UART output

WlanExpNode.ping()

‘Ping’ the node

Send an empty packet to the node via the transport to test connectivity between the host and the node. This is the simplest command that can be processed by the node and is similar to the “ping” command used check network connectivity.

Tx Power and Rate

These commands configure the transmit power and rate selections at the node. Powers and rates are configured individually for various packet types. For unicast packets, Tx powers and rates can be configured for specific destination addresses as well.

WlanExpNode.set_tx_power(power)

Sets the transmit power of the node.

This command will set all transmit power fields on the node to the same value:

• Default Unicast Management Packet Tx Power for new station infos
• Default Unicast Data Packet Tx Power for new station infos
• Default Multicast Management Packet Tx Power for new station infos
• Default Multicast Data Packet Tx Power for new station infos
• Control Packet Tx Power

It will also update the transmit power for any frames destined for any known stations.

Parameters:power (int) – Transmit power in dBm (a value between node.max_tx_power_dbm and node.min_tx_power_dbm)

WlanExpNode.set_tx_power_ctrl(power)

Sets the control packet transmit power of the node.

Only the Tx power of the control packets can be set via wlan_exp. The rate of control packets is determined by the 802.11 standard and control packets will be sent on whatever antenna that cause the control packet to be generated (ie an ack for a reception will go out on the same antenna on which the reception occurred).

Parameters:power (int) – Transmit power in dBm (a value between node.max_tx_power_dbm and node.min_tx_power_dbm)

WlanExpNode.set_tx_rate_data(mcs, phy_mode, device_list=None, update_default_unicast=None, update_default_multicast=None)

Sets the packet transmit rate (mcs, phy_mode) for data frames.

Transmit parameters are maintained on a per-MAC address basis. The device_list argument can be used to select particular devices for which the Tx parameter update applies. The update_default_x arguments can be used to specify that the provided power should be used for any future additions to the node’s device list.

Parameters:

• mcs (int) – Modulation and coding scheme (MCS) index (in [0 .. 7])

• phy_mode (str, int) – PHY mode. Must be one of:

  • 'NONHT': Use 802.11 (a/g) rates
  • 'HTMF': Use 802.11 (n) rates

• device_list (list of WlanExpNode / WlanDevice –

  or ‘ALL_UNICAST’ or ‘ALL_MULTICAST’ or ‘ALL’, optional):

  List of 802.11 devices or single 802.11 device for which to set the unicast packet Tx power to ‘power’. A value of ‘ALL_UNICAST’ will apply the specified power to all unicast receiver addresses. A value of ALL_MULTICAST will apply it to all multicast receiver addresses. A value of ‘ALL’ will apply the specified power to all addresses.

• update_default_unicast (bool) – set the default unicast Tx params to the provided ‘power’.

• update_default_multicast (bool) – set the default multicast Tx params to the provided ‘power’.

One of device_list or update_default_unicast or update_default_multicast

must be set.

WlanExpNode.set_tx_rate_mgmt(mcs, phy_mode, device_list=None, update_default_unicast=None, update_default_multicast=None)

Sets the packet transmit rate (mcs, phy_mode) for management frames.

Transmit parameters are maintained on a per-MAC address basis. The device_list argument can be used to select particular devices for which the Tx parameter update applies. The update_default_x arguments can be used to specify that the provided power should be used for any future additions to the node’s device list.

Parameters:

• mcs (int) – Modulation and coding scheme (MCS) index (in [0 .. 7])

• phy_mode (str, int) – PHY mode. Must be one of:

  • 'NONHT': Use 802.11 (a/g) rates
  • 'HTMF': Use 802.11 (n) rates

• device_list (list of WlanExpNode / WlanDevice –

  or ‘ALL_UNICAST’ or ‘ALL_MULTICAST’ or ‘ALL’, optional):

  List of 802.11 devices or single 802.11 device for which to set the unicast packet Tx power to ‘power’. A value of ‘ALL_UNICAST’ will apply the specified power to all unicast receiver addresses. A value of ALL_MULTICAST will apply it to all multicast receiver addresses. A value of ‘ALL’ will apply the specified power to all addresses.

• update_default_unicast (bool) – set the default unicast Tx params to the provided ‘power’.

• update_default_multicast (bool) – set the default multicast Tx params to the provided ‘power’.

One of device_list or update_default_unicast or update_default_multicast

must be set.

Antenna Modes

These commands control which RF interface is used for Tx and Rx of individual packet types.

WlanExpNode.set_rx_ant_mode(ant_mode)

Sets the receive antenna mode for a node.

Parameters:

ant_mode (str) – Antenna mode; must be one of:

• 'RF_A': receive on RF A interface
• 'RF_B': receive on RF B interface

WlanExpNode.get_rx_ant_mode()

Gets the current receive antenna mode for a node.

Returns:Rx Antenna mode; must be one of:

• 'RF_A': receive on RF A interface
• 'RF_B': receive on RF B interface

Return type:ant_mode (str)

WlanExpNode.set_tx_ant_mode_data(ant_mode, device_list=None, update_default_unicast=None, update_default_multicast=None)

Sets the packet transmit antenna mode for data frames.

Transmit parameters are maintained on a per-MAC address basis. The device_list argument can be used to select particular devices for which the Tx parameter update applies. The update_default_x arguments can be used to specify that the provided power should be used for any future additions to the node’s device list.

Parameters:

• ant_mode (str) – Antenna mode; must be one of:

  • 'RF_A': transmit on RF A interface
  • 'RF_B': transmit on RF B interface

• device_list (list of WlanExpNode / WlanDevice –

  or ‘ALL_UNICAST’ or ‘ALL_MULTICAST’ or ‘ALL’, optional):

  List of 802.11 devices or single 802.11 device for which to set the unicast packet Tx power to ‘power’. A value of ‘ALL_UNICAST’ will apply the specified power to all unicast receiver addresses. A value of ALL_MULTICAST will apply it to all multicast receiver addresses. A value of ‘ALL’ will apply the specified power to all addresses.

• update_default_unicast (bool) – set the default unicast Tx params to the provided ‘ant_mode’.

• update_default_multicast (bool) – set the default multicast Tx params to the provided ‘ant_mode’.

One of device_list or update_default_unicast or update_default_multicast

must be set.

WlanExpNode.set_tx_ant_mode_mgmt(ant_mode, device_list=None, update_default_unicast=None, update_default_multicast=None)

Sets the packet transmit antenna mode for management frames.

Transmit parameters are maintained on a per-MAC address basis. The device_list argument can be used to select particular devices for which the Tx parameter update applies. The update_default_x arguments can be used to specify that the provided power should be used for any future additions to the node’s device list.

Parameters:

• ant_mode (str) – Antenna mode; must be one of:

  • 'RF_A': transmit on RF A interface
  • 'RF_B': transmit on RF B interface

• device_list (list of WlanExpNode / WlanDevice –

  or ‘ALL_UNICAST’ or ‘ALL_MULTICAST’ or ‘ALL’, optional):

  List of 802.11 devices or single 802.11 device for which to set the unicast packet Tx power to ‘power’. A value of ‘ALL_UNICAST’ will apply the specified power to all unicast receiver addresses. A value of ALL_MULTICAST will apply it to all multicast receiver addresses. A value of ‘ALL’ will apply the specified power to all addresses.

• update_default_unicast (bool) – set the default unicast Tx params to the provided ‘ant_mode’.

• update_default_multicast (bool) – set the default multicast Tx params to the provided ‘ant_mode’.

One of device_list or update_default_unicast or update_default_multicast

must be set.

Association State

These WlanExpNode commands are used to modify / query the association state of the node.

WlanExpNode.configure_bss()

Configure the Basic Service Set (BSS) information of the node

Each node is either a member of no BSS (colloquially “unassociated”) or a member of one BSS. A node requires a minimum valid bss_info to be a member of a BSS. Based on the node type, there is a minimum set of fields needed for a valid bss_info.

This method must be overloaded by sub-classes.

See http://warpproject.org/trac/wiki/802.11/wlan_exp/bss for more information about BSSes.

WlanExpNode.get_network_info()

Get information about the network the node is a member of

The NetworkInfo() returned by this method can be accessed like a dictionary and has the following fields:

Field	Description
bssid	BSS ID: 48-bit MAC address
channel	Primary channel. In util.wlan_channels = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 36, 40, 44, 48]
channel_type	Channel Type. Value is one of: 0x00 - ‘BW20’ 0x01 - ‘BW40_SEC_BELOW’ 0x02 - ‘BW40_SEC_ABOVE’
ssid	SSID (32 chars max)
ht_capable	1 - Network is capable of HT PHY mode 0 - Netowrk is not capable of NHT PHY mode
beacon_interval	Beacon interval - In time units of 1024 us’
dtim_period
flags	Value contains 1 bit fields: 0x0001 - ‘KEEP’
capabilities	Supported capabilities of the BSS. Value contains 1 bit fields: 0x0001 - ‘ESS’ 0x0002 - ‘IBSS’ 0x0010 - ‘PRIVACY’
latest_beacon_rx_time	Value of System Time in microseconds of last beacon Rx
latest_beacon_rx_power	Last observed beacon Rx Power (dBm)

Returns:Information about network that the node is a member of (can be None) Return type:network_info (NetworkInfo)

WlanExpNode.get_bss_config()

Get BSS configuration of the network the node is a member of

Returns a dictionary with the following fields:

Field	Description
bssid	BSS ID: 48-bit MAC address
channel	Primary channel. In util.wlan_channels = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 36, 40, 44, 48]
channel_type	Channel Type. Value is one of: 0x00 - ‘BW20’ 0x01 - ‘BW40_SEC_BELOW’ 0x02 - ‘BW40_SEC_ABOVE’
ssid	SSID (32 chars max)
ht_capable	1 - Network is capable of HT PHY mode 0 - Netowrk is not capable of NHT PHY mode
beacon_interval	Beacon interval - In time units of 1024 us’
dtim_period

Returns:BSS configuration of the network that the node is a member of (can be None) Return type:bss_config

WlanExpNode.get_bss_members()

Get the BSS members from the node.

The StationInfo() returned by this method can be accessed like a dictionary and has the following fields:

Field	Description
mac_addr	MAC address of station
id	Identification Index for this station
host_name	String hostname (19 chars max), taken from DHCP DISCOVER packets
flags	Station flags. Value containts 1 bit fields: 0x0001 - ‘KEEP’ 0x0002 - ‘DISABLE_ASSOC_CHECK’ 0x0004 - ‘DOZE’ 0x0008 - ‘HT_CAPABLE’
latest_rx_timestamp	Value of System Time in microseconds of last successful Rx from device
latest_txrx_timestamp	Value of System Time in microseconds of last Tx or successful Rx from device
latest_rx_seq	Sequence number of last packet received from device
tx_phy_mcs	Current PHY MCS index in [0:7] for new transmissions to device
tx_phy_mode	Current PHY mode for new transmissions to deivce
tx_phy_antenna_mode	Current PHY antenna mode in [1:4] for new transmissions to device
tx_phy_power	Current Tx power in dBm for new transmissions to device
tx_mac_flags	Flags for Tx MAC config for new transmissions to device. Value contains 1 bit flags: None defined

Returns:List of StationInfo() BSS members known to the node Return type:station_infos (list of StationInfo)

WlanExpNode.get_station_info_list(device_list=None)

Get the all Station Infos from node.

Parameters:device_list (optional) – single or iterable of WlanExpNode or WlanDevice List of devices for which to get counts. Omit this argument to retrieve all station_info entries from node

The StationInfo() returned by this method can be accessed like a dictionary and has the following fields:

Field	Description
mac_addr	MAC address of station
id	Identification Index for this station
host_name	String hostname (19 chars max), taken from DHCP DISCOVER packets
flags	Station flags. Value containts 1 bit fields: 0x0001 - ‘KEEP’ 0x0002 - ‘DISABLE_ASSOC_CHECK’ 0x0004 - ‘DOZE’ 0x0008 - ‘HT_CAPABLE’
latest_rx_timestamp	Value of System Time in microseconds of last successful Rx from device
latest_txrx_timestamp	Value of System Time in microseconds of last Tx or successful Rx from device
latest_rx_seq	Sequence number of last packet received from device
tx_phy_mcs	Current PHY MCS index in [0:7] for new transmissions to device
tx_phy_mode	Current PHY mode for new transmissions to deivce
tx_phy_antenna_mode	Current PHY antenna mode in [1:4] for new transmissions to device
tx_phy_power	Current Tx power in dBm for new transmissions to device
tx_mac_flags	Flags for Tx MAC config for new transmissions to device. Value contains 1 bit flags: None defined

Returns:List of StationInfo() dictionary-like objects. Length of returned list depends on device_list argument.

If device_list is not provided, the length of the return list will equal the length of the station_info list on the node. If the node’s station_info list is empty this method will return an empty list ([])

If device_list is provided the length of the return list will equal the list of device_list. Each entry in the returned list will either be None (if the node had no matching station_info) or a StationInfo() dictionary-like object (if the node had a matching station_info entry).

Return type:station_infos (list of StationInfo)

WlanExpNode.get_network_list()

Get a list of known networks (NetworkInfo()s) on the node

Returns:List of NetworkInfo() that are known to the node Return type:networks (list of NetworkInfo)

Tx/Rx Packet Counts

These WlanExpNode commands are used to to interact with the counts framework. Counts are kept for for each node in the station info list. If promiscuous counts are enabled, then the node will keep counts for every MAC address overheard (whether the node is in the station info list or not). In order to keep the maximum number of counts recorded on the node to a reasonable amount, there is a maximum number of counts implemented in the C code. When that maximum is reached, then the oldest counts structure of an unassociated node will be overwritten.

WlanExpNode.get_txrx_counts(device_list=None)

Get the Tx/Rx counts data structurs from the node.

Parameters:device_list (list of WlanExpNode, WlanExpNode, WlanDevice, optional) – List of devices for which to get counts. See note below for more information. Returns:TxRxCounts() for the device(s) specified. Return type:counts_dictionary (list of TxRxCounts, TxRxCounts)

The TxRxCounts() structure returned by this method can be accessed like a dictionary and has the following fields:

Field	Description
retrieval_timestamp	Value of System Time in microseconds when structure retrieved from the node
mac_addr	MAC address of remote node whose statics are recorded here
data_num_rx_bytes	Total number of bytes received in DATA packets from remote node (only non-duplicates)
data_num_rx_bytes_total	Total number of bytes received in DATA packets from remote node (including duplicates)
data_num_tx_bytes_success	Total number of bytes successfully transmitted in DATA packets to remote node
data_num_tx_bytes_total	Total number of bytes transmitted (successfully or not) in DATA packets to remote node
data_num_rx_packets	Total number of DATA packets received from remote node
data_num_tx_packets_success	Total number of DATA packets successfully transmitted to remote node
data_num_tx_packets_total	Total number of DATA packets transmitted (successfully or not) to remote node
data_num_tx_attempts	Total number of low-level attempts of DATA packets to remote node (includes re-transmissions)
mgmt_num_rx_bytes	Total number of bytes received in management packets from remote node (only non-duplicates)
mgmt_num_rx_bytes_total	Total number of bytes received in management packets from remote node (including duplicates)
mgmt_num_tx_bytes_success	Total number of bytes successfully transmitted in management packets to remote node
mgmt_num_tx_bytes_total	Total number of bytes transmitted (successfully or not) in management packets to remote node
mgmt_num_rx_packets	Total number of management packets received from remote node (only non-duplicates)
mgmt_num_rx_packets_total	Total number of management packets received from remote node (including duplicates)
mgmt_num_tx_packets_success	Total number of management packets successfully transmitted to remote node
mgmt_num_tx_packets_total	Total number of management packets transmitted (successfully or not) to remote node
mgmt_num_tx_attempts	Total number of low-level attempts of management packets to remote node (includes re-transmissions)

If the device_list is a single device, then a single dictionary or None is returned. If the device_list is a list of devices, then a list of dictionaries will be returned in the same order as the devices in the list. If any of the counts are not there, None will be inserted in the list. If the device_list is not specified, then all the counts on the node will be returned.

Local Traffic Generator (LTG)

These WlanExpNode commands interact with the node’s LTG framework. LTGs provides local traffic sources with configurable destimations, payloads, and traffic loads. These traffic sources are ideal for running experiments without external traffic sources connected via Ethernet.

Creating an LTG consumes memory in the node’s heap. LTG creation can fail if the node’s heap is full. Always remove LTGs you no longer need using the ltg_remove or ltg_remove_all methods.

LTG traffic flows are configured with dedicated classes. See Local Traffic Generators for more information on how the payloads and timing of LTG flows are controlled.

WlanExpNode.ltg_configure(traffic_flow=None, auto_start=None)

WlanExpNode.ltg_get_status(ltg_id_list)

Get the status of the LTG flows.

Parameters:ltg_id_list (list of int, int) – List of LTG flow identifiers or single LTG flow identifier

If the ltg_id_list is a single ID, then a single status tuple is returned. If the ltg_id_list is a list of IDs, then a list of status tuples will be returned in the same order as the IDs in the list.

Returns:

1. valid (bool): Is the LTG ID valid? (True/False)
2. running (bool): Is the LTG currently running? (True/False)
3. start_timestamp (int): Timestamp when the LTG started
4. stop_timestamp (int): Timestamp when the LTG stopped

Return type:status (tuple)

WlanExpNode.ltg_remove(ltg_id_list)

Remove the LTG flows.

Parameters:ltg_id_list (list of int, int) – List of LTG flow identifiers or single LTG flow identifier

WlanExpNode.ltg_start(ltg_id_list)

Start the LTG flow.

Parameters:ltg_id_list (list of int, int) – List of LTG flow identifiers or single LTG flow identifier

WlanExpNode.ltg_stop(ltg_id_list)

Stop the LTG flow to the given nodes.

Parameters:ltg_id_list (list of int, int) – List of LTG flow identifiers or single LTG flow identifier

WlanExpNode.ltg_remove_all()

Stops and removes all LTG flows on the node.

WlanExpNode.ltg_start_all()

Start all LTG flows on the node.

WlanExpNode.ltg_stop_all()

Stop all LTG flows on the node.

Log

These WlanExpNode commands are used to interact with the logging framework. The log occupies a large portion of DRAM which is set in C code during runtime (see wlan_mac_high.h for more information on the memory map; Use log_get_capacity() to see the number of bytes allocated for the log).

The log has the ability to wrap to enable longer experiments. By enabling wrapping and periodically pulling the logs, you can effectively log an experiment for an indefinite amount of time. Also, the log can record the entire payload of the wireless packets. Both the log wrapping and logging of full payloads is off by default and can be modified with the log_configure() command.

WlanExpNode.log_configure(log_enable=None, log_wrap_enable=None, log_full_payloads=None, log_txrx_mpdu=None, log_txrx_ctrl=None)

Configure log with the given flags.

By default all attributes are set to None. Only attributes that are given values will be updated on the node. If an attribute is not specified, then that attribute will retain the same value on the node.

Parameters:

• log_enable (bool) – Enable the event log (Default value on Node: TRUE)
• log_wrap_enable (bool) – Enable event log wrapping (Default value on Node: FALSE)
• log_full_payloads (bool) – Record full Tx/Rx payloads in event log (Default value on Node: FALSE)
• log_txrx_mpdu (bool) – Enable Tx/Rx log entries for MPDU frames (Default value on Node: TRUE)
• log_txrx_ctrl (bool) – Enable Tx/Rx log entries for CTRL frames (Default value on Node: TRUE)

WlanExpNode.log_get(size, offset=0, max_req_size=8388608)

Low level method to retrieve log data from a wlan_exp node.

Parameters:

• size (int) – Number of bytes to read from the log
• offset (int, optional) – Starting byte to read from the log
• max_req_size (int, optional) – Max request size that the transport will fragment the request into.

Returns:

Data from the log corresponding to the input parameters

Return type:

buffer (transport.Buffer)

There is no guarentee that this will return data aligned to event boundaries. Use log_get_indexes() to get event aligned boundaries.

Log reads are not destructive. Log entries will only be destroyed by a log reset or if the log wraps.

During a given log_get() command, the ETH_B Ethernet interface of the node will not be able to respond to any other Ethernet packets that are sent to the node. This could cause the node to drop incoming wlan_exp packets from other wlan_exp instances accessing the node. Therefore, for large requests, having a smaller max_req_size will allow the transport to fragement the command and allow the node to be responsive to multiple hosts.

Some basic analysis shows that fragment sizes of 2**23 (8 MB) add about 2% overhead to the receive time and each command takes less than 1 second (~0.9 sec), which is the default transport timeout.

WlanExpNode.log_get_all_new(log_tail_pad=0, max_req_size=8388608)

Get all “new” entries in the log.

The log_get_all_new() method simplifies retrieving a node’s log over the course of a long experiment. This method keeps track of what log data has already been retrieved from the node, then requests new data as the experiment progresses.

The Python node object maintains internal state about what log data has been read from the node to determine if there is “new” data in the log. Since this state data is maintained in Python and not on the node itself, it is possible for multiple host scripts to read log data using log_get_all_new(). The internal state maintained for log_get_all_new() is only reset when using the node reset method (i.e. node.reset(log=True)).

When a node is adding entries to its log, it will allocate the memory for an entry from the log and then fill in the contents. This means at any given time, the last log entry may have incomplete information. In the current C code all log entries are allocated and written in a single context, so it is impossible for Python to retreive an incomplete log entry.

In case future C code defers updating a previously-allocated log entry, this method supports a log_tail_pad argument which will stop short of retrieving the last bytes of the node’s log data array.

Unfortunately, this means that using a log_tail_pad other than zero will result in return data that is not aligned to a log entry boundary. This should not be an issue if the goal is to periodically read the log data from the node and store it in a file (as seen in the log_capture_continuous.py example). However, this can be an issue if trying to periodically read the log and process the log data directly. In this case, log_tail_pad must be zero and the code has to assume the last entry is invalid. This has not come up very much, but please let us know if this is an issue via the forums.

Parameters:log_tail_pad (int, optional) – Number of bytes from the current end of the “new” entries that will not be read during the call. This is to deal with the case where the node is in the process of modifying the last log entry so it my contain incomplete data and should not be read. Returns:Data from the log that contains all entries since the last time the log was read. Return type:buffer (transport.Buffer)

WlanExpNode.log_get_size()

Get the size of the node’s current log (in bytes).

Returns:Number of bytes in the log Return type:num_bytes (int)

WlanExpNode.log_get_capacity()

Get the total capacity of the node’s log memory allocation (in bytes).

Returns:Number of byte allocated for the log. Return type:capacity (int)

WlanExpNode.log_get_indexes()

Get the indexes that describe the state of the event log.

Returns:

1. oldest_index (int): Log index of the oldest event in the log
2. next_index (int): Log index where the next event will be recorded
3. num_wraps (int): Number of times the log has wrapped

Return type:indexes (tuple)

WlanExpNode.log_get_flags()

Get the flags that describe the event log configuration.

Returns:Integer describing the configuration of the event log.

• 0x0001 - Logging enabled
• 0x0002 - Log wrapping enabled
• 0x0004 - Full payload logging enabled
• 0x0008 - Tx/Rx log entries for MPDU frames enabled
• 0x0010 - Tx/Rx log entries for CTRL frames enabled

Return type:flags (int)

WlanExpNode.log_is_full()

Return whether the log is full or not.

Returns:True if the log is full; False if the log is not full. Return type:status (bool)

WlanExpNode.log_write_exp_info(info_type, message=None)

Write the experiment information provided to the log.

Parameters:

• info_type (int) – Type of the experiment info. This is an arbitrary 16 bit number chosen by the experimentor
• message (int, str, bytes, optional) – Information to be placed in the event log.

Message must be able to be converted to bytearray with ‘UTF-8’ format.

WlanExpNode.log_write_time(time_id=None)

Adds the current time in microseconds to the log.

Parameters:time_id (int, optional) – User providied identifier to be used for the TIME_INFO log entry. If none is provided, a random number will be inserted.

Network Scan

These WlanExpNode commands are used to to scan the node’s environment.

WlanExpNode.set_scan_parameters(time_per_channel=None, num_probe_tx_per_channel=None, channel_list=None, ssid=None)

Set the paramters of the wireless network scan state machine.

Parameters:

• time_per_channel (float, optional) – Time (in float sec) to spend on each channel. A value of None will not modify the current time per channel
• num_probe_tx_per_channel (int, optional) – Number of probe requests transmitted while on each channel. A value of None will not modify the current number of probe requests per channel.
• channel_list (list of int optional) – Channel(s) to scan; A value of None will not modify the current channel list.
• ssid (str, optional) – SSID to scan for (as part of probe request); A value of None will not modify the current SSID.

Setting num_probe_tx_per_chan to a non-zero value will enable active scanning. The node will transmit broadcast Probe Request packets on every channel and will gather network information from received Probe Response and Beacon packets. Setting num_probe_tx_per_chan=0 will enable passive scanning. In this mode the node will not transmit any Probe Request packets and network information will be gathered only from received Beacon packets.

The blank SSID (ssid="") is interpretted as a wildcard and will solicit Probe Response packets from networks with any SSID. “Closed” networks do not respond to the wildcard SSID. These networks will still be discovered via Beacon receptions.

If the channel list / SSID is not specified, then it will not be updated on the node (ie it will use the current channel list / SSID)

WlanExpNode.start_network_scan()

Starts the wireless network scan state machine at the node.

During a scan, the node cycles through a set of channels and transmits periodic Probe Request frames on each channel. Information about available wireless networks is extracted from received Probe Responses and Beacon frames. The network scan results can be queried any time using the node.get_network_list() method.

Network scans can only be run by unassociated nodes. An associated node must first reset its BSS state before starting a scan.

The network scan state machine can be stopped with node.stop_network_scan(). The scan state machine will also be stopped automatically if the node is configured with a new non-null BSS state.

Example:

# Ensure node has null BSS state
n.configure_bss(None)

# Start the scan state machine; scan will use default scan params
#  Use n.set_scan_parameters() to customize scan behavior
n.start_network_scan()

# Wait 5 seconds, retrieve the list of discovered networks
time.sleep(5)
networks = n.get_network_list()

# Stop the scan state machine
n.stop_network_scan()

WlanExpNode.stop_network_scan()

Stops the wireless network scan state machine.

WlanExpNode.is_scanning()

Queries if the node’s wireless network scanning state machine is currently running.

Returns:

• True – Scan state machine is running
• False – Scan state machine is not running

Return type:status (bool)