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)[source]¶ Class for 802.11 Reference Design Experiments Framwork node.
Parameters: network_config (transport.NetworkConfiguration) – Network configuration of the node
Variables: - node_type (int) – Unique type of the node
- 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)
- hw_ver (int) – Hardware version of this node
- transport (transport.Transport) – Node’s transport object
- transport_broadcast (transport.Transport) – Node’s broadcast transport object
- device_type (int) – Unique type of the
WlanDevice
(inherited fromWlanDevice
) - 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_resolution (int) – Minimum resolution (in us) of the scheduler. This is also the minimum time between LTGs.
- 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.
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
()[source]¶ Resets all portions of a node.
This includes:
- Log
- Counts
- Local Traffic Generators (LTGs)
- Queues
- BSS (i.e. all network state)
- Observed Networks
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, queue_data=False, bss=False, network_list=False)[source]¶ 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 bylog_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.
queue_data (bool) – Purge all TX queue data. 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. Also, this will not stop additional packets from sources such as LTGs from being enqueued.
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) – Remove all BSS entries from the network list, excluding the BSS entry for the node’s current network (if any)
-
WlanExpNode.
get_wlan_mac_address
()[source]¶ Get the WLAN MAC Address of the node.
Returns: MAC Address – Wireless Medium Access Control (MAC) address of the node. Return type: int
-
WlanExpNode.
set_mac_time
(time, time_id=None)[source]¶ 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
()[source]¶ Gets the MAC time from the node.
Returns: time – Timestamp of the MAC time of the node in int microseconds Return type: int
-
WlanExpNode.
get_system_time
()[source]¶ Gets the system time from the node.
Returns: Time – Timestamp of the System time of the node in int microseconds Return type: int
-
WlanExpNode.
enable_beacon_mac_time_update
(enable)[source]¶ Enable / Disable MAC time update from received beacons.
Parameters: enable (bool) – True
enables andFalse
disables MAC time updates from received beacons
-
WlanExpNode.
set_radio_channel
(channel)[source]¶ 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)[source]¶ 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'
andfcs='ALL'
.- mac_header (str, optional) –
MAC header filter. Values can be:
-
WlanExpNode.
set_low_param
(param_id, param_values)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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 messagesERROR
- Only print error messagesWARNING
- Print error and warning messagesINFO
- Print error, warning and info messagesDEBUG
- Print error, warning, info and debug messages
-
WlanExpNode.
enable_ethernet_portal
(enable)[source]¶ 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 andFalse
disables Ethernet portal functionality
-
WlanExpNode.
queue_tx_data_purge_all
()[source]¶ Purges all data transmit queues on the node.
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. Also, this will not stop additional packets from sources such as LTGs from being enqueued.
This command is equivalent to
reset(queue_data=True)
.
-
WlanExpNode.
send_user_command
(cmd_id, args=None)[source]¶ 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: resp_args – List of u32 response arguments received from the node
Return type: 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)[source]¶ 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
andnode.min_tx_power_dbm
)
-
WlanExpNode.
set_tx_power_ctrl
(power)[source]¶ 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
andnode.min_tx_power_dbm
)
Antenna Modes¶
These commands control which RF interface is used for Tx and Rx of individual packet types.
Association State¶
These WlanExpNode
commands are used to modify / query the association state of the node.
-
WlanExpNode.
configure_bss
()[source]¶ 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
()[source]¶ 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:
Returns: network_info – Information about network that the node is a member of (can be None) Return type: NetworkInfo
-
WlanExpNode.
get_bss_config
()[source]¶ Get BSS configuration of the network the node is a member of
Returns a dictionary with the following fields:
Returns: BSS configuration of the network that the node is a member of (can be None) Return type: bss_config
-
WlanExpNode.
get_bss_members
()[source]¶ 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: station_infos – List of StationInfo() BSS members known to the node Return type: list of StationInfo
-
WlanExpNode.
get_station_info_list
()[source]¶ Get the all Station Infos 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: station_infos – List of all StationInfo() known to the node Return type: list of StationInfo
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, return_zeroed_counts_if_none=False)[source]¶ 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.
return_zeroed_counts_if_none (bool, optional) – If no counts exist on the node for the specified device(s), return a zeroed counts dictionary with proper timestamps instead of None.
Returns: counts_dictionary – TxRxCounts() for the device(s) specified.
Return type: 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 thedevice_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 thedevice_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 LTG Flow Configurations for more information on how the payloads and timing of LTG flows are controlled.
-
WlanExpNode.
ltg_configure
(traffic_flow, auto_start=False)[source]¶ Configure the node for the given traffic flow.
Parameters: - traffic_flow (ltg.FlowConfig) – FlowConfig (or subclass of FlowConfig) that describes the parameters of the LTG.
- auto_start (bool, optional) – Automatically start the LTG or wait until it is explictly started.
Returns: ID – Identifier for the LTG flow
Return type: int
The
trafic_flow
argument configures the behavior of the LTG, including the traffic’s destination, packet payloads, and packet generation timing. The reference code implements three flow configurations by default:FlowConfigCBR()
: a constant bit rate (CBR) source targeted to a specifc destination address. Packet lengths and the packet creation interval are constant.FlowConfigAllAssocCBR()
: a CBR source that targets traffic to all nodes in the station info list.FlowConfigRandomRandom()
: a source that targets traffic to a specific destination address, where each packet has a random length and packets are created at random intervals.
Refer to the LTG Flow Configurations documentation for details on these flow configs and the underlying classes that can be used to build custom flow configurations.
Examples
The code below illustrates a few LTG configuration examples.
n1
andn2
here are a wlan_exp node objects and the LTG traffic in each flow will go fromn1
ton2
.import wlan_exp.ltg as ltg # Configure a CBR LTG addressed to a single node ltg_id = n1.ltg_configure(ltg.FlowConfigCBR(dest_addr=n2.wlan_mac_address, payload_length=40, interval=0.01), auto_start=True) # Configure a backlogged traffic source with constant packet size ltg_id = n1.ltg_configure(ltg.FlowConfigCBR(dest_addr=n2.wlan_mac_address, payload_length=1000, interval=0), auto_start=True) # Configure a random traffic source ltg_id = n1.ltg_configure(ltg.FlowConfigRandomRandom(dest_addr=n2.wlan_mac_address, min_payload_length=100, max_payload_length=500, min_interval=0, max_interval=0.1), auto_start=True)
-
WlanExpNode.
ltg_get_status
(ltg_id_list)[source]¶ 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: status – - valid (bool): Is the LTG ID valid? (True/False)
- running (bool): Is the LTG currently running? (True/False)
- start_timestamp (int): Timestamp when the LTG started
- stop_timestamp (int): Timestamp when the LTG stopped
Return type: tuple
-
WlanExpNode.
ltg_remove
(ltg_id_list)[source]¶ 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)[source]¶ Start the LTG flow.
Parameters: ltg_id_list (list of int, int) – List of LTG flow identifiers or single LTG flow identifier
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)[source]¶ 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)[source]¶ 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: buffer – Data from the log corresponding to the input parameters
Return type: 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 smallermax_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=500, max_req_size=8388608)[source]¶ Get all “new” entries in the log.
In order to make reading log data easier, the
log_get_all_new()
command was created. It utilizes thelog_get_indexex()
andlog_get()
commmands to understand the state of the log and to retrieve data from the log. The Python node object also 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 usinglog_get_all_new()
. The internal state maintained forlog_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. Currently, the log maintains the index where the next log entry will be recorded (i.e. the
next_index
), which does not provide any state about whether the last log entry has been completed. Therefore, in order to not retrieve incomplete information,log_get_all_new()
has an argumentlog_tail_pad=N
to not read the last N “new” bytes of log data.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 thelog_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: buffer – Data from the log that contains all entries since the last time the log was read. Return type: transport.Buffer
-
WlanExpNode.
log_get_size
()[source]¶ Get the size of the node’s current log (in bytes).
Returns: num_bytes – Number of bytes in the log Return type: int
-
WlanExpNode.
log_get_capacity
()[source]¶ Get the total capacity of the node’s log memory allocation (in bytes).
Returns: capacity – Number of byte allocated for the log. Return type: int
-
WlanExpNode.
log_get_indexes
()[source]¶ Get the indexes that describe the state of the event log.
Returns: indexes – - oldest_index (int): Log index of the oldest event in the log
- next_index (int): Log index where the next event will be recorded
- num_wraps (int): Number of times the log has wrapped
Return type: tuple
-
WlanExpNode.
log_get_flags
()[source]¶ Get the flags that describe the event log configuration.
Returns: flags – Integer describing the configuration of the event log. 0x0001
- Logging enabled0x0002
- Log wrapping enabled0x0004
- Full payload logging enabled0x0008
- Tx/Rx log entries for MPDU frames enabled0x0010
- Tx/Rx log entries for CTRL frames enabled
Return type: int
-
WlanExpNode.
log_is_full
()[source]¶ Return whether the log is full or not.
Returns: status – True if the log is full; False if the log is not full. Return type: bool
-
WlanExpNode.
log_write_exp_info
(info_type, message=None)[source]¶ 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.
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)[source]¶ 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. Settingnum_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
()[source]¶ 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()