wiki:802.11/wlan_exp/Porting_v1.5

Version 5 (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

Tx/Rx Entry Changes

phy_mode Field 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.

mcs Field 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 Field 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 Field 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.

Renamed TX entry type to TX_HIGH The TX_HIGH entry type (named TX in previous releases) records each packet which passes through a queue in the upper MAC framework. Each TX_HIGH entry will have 0 or more TX_LOW entries, depending on how the lower MAC handles the transmission event.