WLAN Exp Utilities¶

Common utilities for the WLAN Experiment framework.

UART Print Levels¶

Defined UART print levels to control the verbosity of the wlan_exp UART output.

uart_print_levels = {'DEBUG': 4, 'ERROR': 1, 'INFO': 3, 'NONE': 0, 'WARNING': 2}¶

Contants Dictionary

Sub-class of dictionary, with fields accessible as immutable properties.

Transmit / Receive Rate Definitions¶

Supported transmit / receive rates for WlanExpNode

phy_modes = {'DSSS': 0, 'HTMF': 2, 'NONHT': 1}¶

PHY Modes

‘DSSS’ - DSSS (Rx only)

‘NONHT’ - NONHT OFDM (11a/g)

‘HTMF’ - HTMF (11n)

Use this dictionary to interpret phy_mode values encoded in Tx/Rx log entries

get_rate_info(mcs, phy_mode, phy_samp_rate=20, short_GI=False)[source]¶

Generate dictionary with details about a PHY rate. The returned dictionary has fields:

mcs: the MCS index passed in the mcs argument, integer in 0 to 7

phy_mode: the PHY mode passed in the phy_mode argument, either 'NONHT' or 'HTMF'

desc: string describing the rate

NDBPS: integer number of data bits per OFDM symbol for the rate

phy_rate: float data rate in Mbps

Parameters:	mcs (int) – Modulation and coding scheme (MCS) index phy_mode (str, int) – PHY mode (‘NONHT’, ‘HTMF’) phy_samp_rate (int) – PHY sampling rate (10, 20, 40) short_GI (bool) – Short Guard Interval (GI) (True/False)
Returns:	Rate info dictionary
Return type:	rate_info (dict)

rate_info_to_str(rate_info)[source]¶

Convert dictionary returned by get_rate_info() into a printable string.

Parameters:	rate_info (dict) – Dictionary returned by `get_rate_info()`
Returns:	String representation of the rate
Return type:	output (str)

Example

>>> import wlan_exp.util as util
>>> r = util.get_rate_info(mcs=3, phy_mode='HTMF')
>>> print(util.rate_info_to_str(r))
26.0 Mbps (HTMF 16-QAM 1/2)

Channel Definitions¶

Supported channels for WlanExpNode

wlan_channels = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 36, 40, 44, 48]¶: List of supported channels. Each value represents a 20MHz channel in the 2.4GHz or 5GHz bands. Use the get_channel_info method to lookup the actual center frequency for a given channel index.

get_channel_info(channel)[source]¶

Get channel info dictionary based on channel number

Parameters:	channel (int) – Number of 802.11 channel (https://en.wikipedia.org/wiki/List_of_WLAN_channels)
Returns:	Channel info dictionary
Return type:	channel_info (dict)

The returned dictionary has fields:

channel: Integer channel index

freq: Integer channel center frequency, in MHz

Examples

>>> import wlan_exp.util as util
>>> util.get_channel_info(5)
{'freq': 2432, 'channel': 5}

channel_info_to_str(channel_info)[source]¶

Convert a channel info dictionary to a string.

Parameters:	channel_info (dict) – Dictionary returned by `get_channel_info()`
Returns:	String representation of the ‘channel’
Return type:	output (str)

Antenna Mode Definitions¶

Supported antenna modes for WlanExpNode

util.wlan_rx_ant_modes = Dictionary of receive antenna modes¶

util.wlan_tx_ant_modes = Dictionary of transmit antenna modes¶

MAC Address Definitions¶

Pre-defined MAC address constants

util.mac_addr_desc_map = List of tuples (MAC value, mask, description) that describe various MAC address ranges¶

util.mac_addr_mcast_mask = Multicast MAC Address Mask¶

util.mac_addr_local_mask = Local MAC Address Mask¶

util.mac_addr_broadcast = Broadcast MAC Address¶

Node Utility Functions¶

init_nodes(nodes_config, network_config=None, node_factory=None, network_reset=True, output=False)[source]¶

Initalize wlan_exp nodes.

The init_nodes function serves two purposes: 1) To initialize the node for participation in the experiment and 2) To retrieve all necessary information from the node to provide a valid python WlanExpNode object to be used in the experiment script.

When a node is first configured from a bitstream, its network interface is set to a default value such that it is part of the defalt subnet 10.0.0 but does not have a valid IP address for communication with the host. As part of the init_nodes process, if network_reset is True, the host will reset the network configuration on the node and configure the node with a valid IP address. If the network settings of a node have already been configured and are known to the python experiment script a priori, then it is not necessary to issue a network reset to reset the network settings on the node. This can be extremely useful when trying to interact with a node via multiple python experiment scripts at the same time.

Parameters:	nodes_config (NodesConfiguration) – A NodesConfiguration describing the nodes in the network. network_config (NetworkConfiguration, optional) – A NetworkConfiguration object describing the network configuration node_factory (WlanExpNodeFactory, optional) – A WlanExpNodeFactory or subclass to create nodes of a given node type network_reset (bool, optional) – Issue a network reset command to the nodes to initialize / re-initialize their network interface. output (bool, optional) – Print output about the nodes
Returns:	Initialized list of WlanExpNode / sub-classes of WlanExpNode depending on the hardware configuration of the nodes.
Return type:	nodes (list of WlanExpNode)

broadcast_cmd_set_mac_time(time, network_config, time_id=None)[source]¶

Initialize the MAC time on all of the wlan_exp nodes.

This method will iterate through all network configurations and issue a broadcast packet on each network that will set the MAC time on the node to ‘time’. The method keeps track of how long it takes to send each packet so that the time on all nodes is as close as possible even across networks.

Parameters:

network_config (NetworkConfiguration) – One or more NetworkConfiguration objects that define the networks on which the set_time command will be broadcast
time (int) – Time to which the node’s MAC timestamp will be set (int 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.

broadcast_cmd_write_time_to_logs(network_config, time_id=None)[source]¶

Add the current host time to the log on each node.

This method will iterate through all network configurations and issue a broadcast packet on each network that will add the current time to the log. The method keeps track of how long it takes to send each packet so that the time on all nodes is as close as possible even across networks.

Parameters:	network_config (NetworkConfiguration) – One or more NetworkConfiguration objects that define the networks on which the log_write_time command will be broadcast 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.

broadcast_cmd_write_exp_info_to_logs(network_config, info_type, message=None)[source]¶

Add the EXP INFO log entry to the log on each node.

This method will iterate through all network configurations and issue a broadcast packet on each network that will add the EXP_INFO log entry to the log

Parameters:	network_config (NetworkConfiguration) – One or more NetworkConfiguration objects that define the networks on which the log_write_exp_info command will be broadcast 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.

filter_nodes(nodes, mac_high=None, mac_low=None, serial_number=None, warn=True)[source]¶

Return a list of nodes that match all the values for the given filter parameters.

Each of these filter parameters can be a single value or a list of values.

Parameters:	nodes (list of WlanExpNode) – List of WlanExpNode / sub-classes of WlanExpNode mac_high (str, int, optional) – Filter for CPU High functionality. This value must be either an integer corresponding to a node type (see wlan_exp/defaults.py for node types) or the following strings: ‘AP’ (equivalent to WLAN_EXP_HIGH_AP); ‘STA’ (equivalent to WLAN_EXP_HIGH_STA); ‘IBSS’ (equivalent to WLAN_EXP_HIGH_IBSS). A value of None means that no filtering will occur for CPU High Functionality mac_low (str, int, optional) – Filter for CPU Low functionality. This value must be either an integer corresponding to a node type (see wlan_exp/defaults.py for node types) or the following strings: ‘DCF’ (equivalent to WLAN_EXP_LOW_DCF); ‘NOMAC’ (equivalent to WLAN_EXP_LOW_NOMAC). A value of None means that no filtering will occur for CPU Low Functionality serial_number (str, optional) – Filters nodes by serial number. warn (bool, optional) – Print warnings (default value is True)
Returns:	Filtered list of WlanExpNode / sub-classes of WlanExpNode
Return type:	nodes (list of WlanExpNode)

If the return list of nodes is empty, then this method will issue a warning if the parameter warn is True.

Examples

>>> filter_nodes(nodes, mac_high='AP', mac_low='DCF')
>>> filter_nodes(nodes, mac_high='AP')
>>> filter_nodes(nodes, mac_high='AP', mac_low='DCF', serial_numbers=['w3-a-00001','w3-a-00002'])

check_bss_membership(nodes, verbose=False)[source]¶

Check that each of the nodes in the input list are members of the same BSS. For a BSS to match, the ‘bssid’, ‘ssid’ and ‘channel’ must match.

There are two acceptable patterns for the nodes argument

1 AP and 1+ STA and 0 IBSS (“infrastructure” network)

0 AP and 0 STA and 2+ IBSS (“ad hoc” network)

In the case that nodes is 1 AP and 1+ STA and 0 IBSS, then the following conditions must be met in order to return True

AP BSS must be non-null

AP must have each STA in its station_info list

Each STA BSS must match AP BSS

Each STA must have AP as its only station_info. In the current STA implementation this condition is guaranteed if the STA BSS matches the AP BSS (previous condition)

In the case that nodes is 0 AP and 0 STA and 2+ IBSS, then the following conditions must be met in order to return True

BSS must match at all nodes and be non-null

Parameters:	nodes (list of WlanExpNode) – List of WlanExpNode / sub-classes of WlanExpNode verbose (bool) – Print details on which nodes fail BSS membership checks
Returns:	Boolean indicating whether the nodes were members of the same BSS
Return type:	members (bool)

Misc Utility Functions¶

create_locally_administered_bssid(mac_address)[source]¶

Create a locally administered BSSID.

Set “locally administered” bit to ‘1’ and “multicast” bit to ‘0’

Parameters:	mac_address (int, str) – MAC address to be used as the base for the BSSID either as a 48-bit integer or a colon delimited string of the form: XX:XX:XX:XX:XX:XX
Returns:	BSSID with the “locally administerd” bit set to ‘1’ and the “multicast” bit set to ‘0’
Return type:	bssid (int)

int_to_ip(ip_address)[source]¶

Convert an integer to IP address string (dotted notation).

Parameters:	ip_address (int) – Unsigned 32-bit integer representation of the IP address
Returns:	String version of an IP address of the form W.X.Y.Z
Return type:	ip_address (str)

ip_to_int(ip_address)[source]¶

Convert IP address string (dotted notation) to an integer.

Parameters:	ip_address (str) – String version of an IP address of the form W.X.Y.Z
Returns:	Unsigned 32-bit integer representation of the IP address
Return type:	ip_address (int)

mac_addr_to_str(mac_address)[source]¶

Convert an integer to a colon separated MAC address string.

Parameters:	mac_address (int) – Unsigned 48-bit integer representation of the MAC address
Returns:	String version of an MAC address of the form XX:XX:XX:XX:XX:XX
Return type:	mac_address (str)

str_to_mac_addr(mac_address)[source]¶

Convert a colon separated MAC address string to an integer.

Parameters:	mac_address (str) – String version of an MAC address of the form XX:XX:XX:XX:XX:XX
Returns:	Unsigned 48-bit integer representation of the MAC address
Return type:	mac_address (int)

mac_addr_to_byte_str(mac_address)[source]¶

Convert an integer to a MAC address byte string.

Parameters:	mac_address (int) – Unsigned 48-bit integer representation of the MAC address
Returns:	Byte string version of an MAC address
Return type:	mac_address (str)

byte_str_to_mac_addr(mac_address)[source]¶

Convert a MAC address byte string to an integer.

Parameters:	mac_address (str) – Byte string version of an MAC address
Returns:	Unsigned 48-bit integer representation of the MAC address
Return type:	mac_address (int)

sn_to_str(platform_id, serial_number)[source]¶

Convert serial number to a string for a given hardware generation.

Parameters:	platform_id (int) – Platform ID (currently only ‘3’ is supported) serial_number (int) – Integer part of the node’s serial number
Returns:	String representation of the node’s serial number
Return type:	serial_number (str)

node_type_to_str(node_type, node_factory=None)[source]¶

Convert the Node Type to a string description.

Parameters:	node_type (int) – node type ID (u32) node_factory (WlanExpNodeFactory) – A WlanExpNodeFactory or subclass to create nodes of a given type
Returns:	String representation of the node type
Return type:	node_type (str)

By default, a dictionary of node types is built dynamically during init_nodes(). If init_nodes() has not been run, then the method will try to create a node type dictionary. If a node_factory is not provided then a default WlanExpNodeFactory will be used to determine the node type. If a default WlanExpNodeFactory is used, then only framework node types will be known and custom node types will return: “Unknown node type: <value>”

mac_addr_desc(mac_addr, desc_map=None)[source]¶

Returns a string description of a MAC address.

This is useful when printing a table of addresses. Custom MAC address descriptions can be provided via the desc_map argument. In addition to the provided desc_map, the global mac_addr_desc_map that describes mappings of different MAC addresses will also be used.

Parameters:	mac_address (int) – 64-bit integer representing 48-bit MAC address desc_map (list of tuple, optional) – list of tuple or tuple of the form (addr_mask, addr_value, descritpion)
Returns:	Description of the MAC address or ‘’ if address does not match any descriptions
Return type:	description (str)

The mac_address argument will be bitwise AND’d with each addr_mask, then compared to addr_value. If the result is non-zero the corresponding descprition will be returned. This will only return the first description in the [desc_map, mac_addr_desc_map] list.

debug_here(banner=None)[source]¶

Function that mimics the matlab keyboard command for interactive debbug.

Parameters:	banner (str) – Banner message to be displayed before the interactive prompt