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 = {'INFO': 3, 'DEBUG': 4, 'NONE': 0, 'WARNING': 2, 'ERROR': 1}

wlan_exp 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

Use this dictionary for the set_print_level() command

Transmit / Receive Rate Definitions

Supported transmit / receive rates for WlanExpNode

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

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 – Rate info dictionary

Return type:

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:output – String representation of the rate
Return type: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 – Channel info dictionary
Return type: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:output – String representation of the ‘channel’
Return type: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:

nodes – Initialized list of WlanExpNode / sub-classes of WlanExpNode depending on the hardware configuration of the nodes.

Return type:

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:

nodes – Filtered list of WlanExpNode / sub-classes of WlanExpNode

Return type:

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. 1 AP and 1+ STA and 0 IBSS (“infrastructure” network)
  2. 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

  1. AP BSS must be non-null
  2. AP must have each STA in its station_info list
  3. Each STA BSS must match AP BSS
  4. 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

  1. 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:

members – Boolean indicating whether the nodes were members of the same BSS

Return type:

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 – BSSID with the “locally administerd” bit set to ‘1’ and the “multicast” bit set to ‘0’
Return type: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:ip_address – String version of an IP address of the form W.X.Y.Z
Return type: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:ip_address – Unsigned 32-bit integer representation of the IP address
Return type: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:mac_address – String version of an MAC address of the form XX:XX:XX:XX:XX:XX
Return type: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:mac_address – Unsigned 48-bit integer representation of the MAC address
Return type: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:mac_address – Byte string version of an MAC address
Return type: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:mac_address – Unsigned 48-bit integer representation of the MAC address
Return type: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:

serial_number – String representation of the node’s serial number

Return type:

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:

node_type – String representation of the node type

Return 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 – Description of the MAC address or ‘’ if address does not match any descriptions

Return type:

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