wiki:802.11/wlan_exp/Porting_v1.5

Version 9 (modified by murphpo, 8 years ago) (diff)

--

802.11 Reference Design: Porting to wlan_exp v1.5

The 802.11 Reference Design v1.5 release included many improvements to the wlan_exp Python package. These improvements required numerous API changes. The example wlan_exp scripts have been updated with the new v1.5 API.

In order to assist with porting custom scrtips, the sections below highlight some of the changes from v1.4 to v1.5.

Setup AP+STA network

wlan_exp v1.4

wlan_exp v1.5

# Create simple AP+STA network
n_ap.disassociate_all()
n_ap.set_ssid('WARP-AP')
n_ap.add_association(n_sta)
n_ap.set_channel(6)
n_sta.set_channel(6)
# Create simple AP+STA network
n_ap.configure_bss(ssid='WARP-AP', channel=6)
n_ap.add_association(n_sta)

Configuring Tx Rates

Two key changes for the set_tx_rate methods:

  • Require mcs argument for MCS index, instead of using entry from a dictionary of rates
  • Require phy_mode argument to select between 11a ('NONHT') and 11n ('HTMF') rates

wlan_exp v1.4

wlan_exp v1.5

# Select QPSK 1/2 rate for all DATA Tx
rate = wlan_exp_util.wlan_rates[2]
n.set_tx_rate_unicast(rate, curr_assoc=True, new_assoc=True)
n_ap.set_tx_rate_multicast_data(rate)
# Select non-HT QPSK 1/2 rate for all DATA Tx
n.set_tx_rate_unicast(mcs=2, phy_mode='NONHT', curr_assoc=True, new_assoc=True)
n_ap.set_tx_rate_multicast_data(mcs=2, phy_mode='NONHT')

Configuring Antenna Modes

Methods for setting Tx and Rx antenna modes now accept simple string argument values, replacing the dictionaries of antenna modes. The new set_tx_ant_mode helper method sets the Tx antenna mode for all classes of traffic and all partners. Different Tx antenna modes can still be set per traffic class / per partner device - refer to the wlan_exp antenna modes docs for details.

wlan_exp v1.4

wlan_exp v1.5

# Select RF B for all Tx
m_tx = wlan_exp_util.wlan_tx_ant_mode[1]
n.set_tx_ant_mode_unicast(m, curr_assoc=True, new_assoc=True)
n.set_tx_ant_mode_multicast_data(m, curr_assoc=True, new_assoc=True)
n.set_tx_ant_mode_multicast_mgmt(m, curr_assoc=True, new_assoc=True)

# Select RF B for all Rx
m_rx = wlan_exp_util.wlan_rx_ant_mode[1]
n.set_rx_ant_mode(m_rx)
# Select RF B for all Tx and Rx
n.set_tx_ant_mode('RF_B')
n.set_rx_ant_mode('RF_B')

Other API Changes

The table below lists some other changes to the wlan_exp API. For complete wlan_exp documentation refer to the wlan_exp HTML docs.

Deprecated Replacement Docs Link
n_ap.ap_configure(support_power_savings=bool) n_ap.enable_DTIM_multicast_buffering(bool) docs
n_sta.sta_configure(bool n_sta.enable_beacon_mac_time_update(bool) docs
n_ibss.ibss_configure(bool n_ibss.enable_beacon_mac_time_update(bool) docs

Event Log Changes

Entry Type Constants

Various log entry type fields encode values as "magic" numbers. The C code uses #define and enum to encode the field values. Starting in v1.5 the wlan_exp framework provides a convenient container to encode the same constants for use in log processing scripts. The constant definitions are stored per log entry type. The constants for a given entry type can be retrieved with c = log_util.get_entry_constants('ENTRY_TYPE_NAME'). The return value is a dictionary-like object with keys for each field in the log entry with constant definitions. The constants dictionary can be accessed with normal dictionary syntax d['field'] or with field names as properties d.field. The contents of the returned object cannot be changed.

For example, consider the RX_OFDM entry type:

>>> c_rx = log_util.get_entry_constants('RX_OFDM')
>>> c_rx
{'flags': {'DUPLICATE': 2, 'FCS_GOOD': 1, 'LTG': 128, 'LTG_PYLD': 64},
 'phy_mode': {'DSSS': 0, 'HTMF': 2, 'NONHT': 1},
 'pkt_type': {'ACK': 212,
              'BEACON': 128,
              'CTS': 196,
              'DATA': 8,
              'NULLDATA': 72,
              'PROBE_RESP': 80,
              'QOSDATA': 136,
              'RTS': 180}}

>>> c_rx.phy_mode['HTMF']
2

These constants are useful when filtering arrays of log entries. For example, assume n_log_rx is a numpy array of RX_OFDM entries:

>>> c_rx = log_util.get_entry_constants('RX_OFDM')

# Extract FCS Good Rx
>>> rx_good = n_log_rx[ (n_log_rx['flags'] & c_rx.flags['FCS_GOOD']) != 0) ]

# Extract Beacon Rx
>>> rx_beacon = n_log_rx[ (n_log_rx['pkt_type'] == c_rx.pkt_type['BEACON']) ]

The wlan_exp example scripts have been updated to use the per-entry-type constants.

Tx/Rx Entry Changes

Various fields in the Tx and Rx entry types are updated in v1.5.

v1.4

v1.5

Notes

n/a

phy_mode

Starting in v1.5 the reference design supports both non-HT (11a) and HTMF (11n) waveforms. The Tx and Rx PHY can switch between PHY modes per-packet. The Tx/Rx log entries have a phy_mode field which encodes which mode was used for a given Tx/Rx event. The NONHT PHY mode (11a) has value 1; the HTMF PHY mode (11n) has value 2.

rate

mcs

Previous releases defined a rate field in Tx and Rx entries. The rate value was an index into the array of 8 supported 11a rates. Starting in v1.5 the rate field is replaced by mcs and always records the MCS index of the Tx/Rx waveform. The mcs value must be combined with the phy_mode value to know what PHY rate and mode were used for a given Tx/Rx event.}}}

pkt_type

pkt_type

Previous releases defined a pkt_type field in Tx and Rx log entries. This field had values like LTG and ACK. The mapping of 802.11 packet types to pkt_type values was arbitrary, implemented in the reference C code. Starting in v1.5 the pkt_type field is a copy of the 1-byte frame_control1 field from the packet's 802.11 header. This field encodes the type (Data, Management or Control) and sub-type (i.e. QoS Data, Protected Data; Probe Request, Beacon; RTS, ACK). The reference code does not modify the type/sub-type values recorded in the pkt_type log entries.

timestamp_frac

timestamp_frac

Tx/Rx entries have always had a timestamp field which records the MAC Time in microseconds of each Tx/Rx event. Starting in v1.5 the MAC/PHY hardware also records a "fractional" timestamp for Tx/Rx events. By combining the timestamp and timestamp_frac values the timing of a Tx/Rx event can be resolved with sample-period accuracy.

The fractional timestamp value records the value of the counter in the wlan_mac_time_hw core which defines the microsecond intervals for the MAC and System Times. This counter counts from 0 to 159 at 160MHz (i.e. 160 cycles @ 160MHz = 1 µsec). Thus the timestamp_frac field will have values in [0, 1, ... 159]. To translate this value into a fraction of a microsecond, divide the timestamp_frac value by 160.