{{{#!comment
[[Include(wiki:802.11/beta-note)]]
}}}

[[TracNav(802.11/TOC)]]

= 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 [../examples 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

{{{#!th 
'''wlan_exp v1.4'''
}}}
{{{#!th 
'''wlan_exp v1.5'''
}}}
{{{#!tr valign=top

{{{#!td
{{{#!python
# 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)
}}}
}}}
{{{#!td
{{{#!python
# 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

{{{#!th 
'''wlan_exp v1.4'''
}}}
{{{#!th 
'''wlan_exp v1.5'''
}}}
{{{#!tr valign=top

{{{#!td
{{{#!python
# 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)
}}}
}}}
{{{#!td
{{{#!python
# 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 [//docs/mango-wlan-exp/node.html#antenna-modes wlan_exp antenna modes docs] for details.


{{{#!th 
'''wlan_exp v1.4'''
}}}
{{{#!th 
'''wlan_exp v1.5'''
}}}
{{{#!tr valign=top

{{{#!td
{{{#!python
# 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)
}}}
}}}
{{{#!td
{{{#!python
# 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 [//docs/mango-wlan-exp/index.html wlan_exp HTML docs].
||= Deprecated =||= Replacement =||= Docs Link =||
|| {{{n_ap.ap_configure(support_power_savings=bool)}}} || {{{n_ap.enable_DTIM_multicast_buffering(bool)}}} ||  [//docs/mango-wlan-exp/node_ap.html#wlan_exp.node_ap.WlanExpNodeAp.enable_DTIM_multicast_buffering docs]  ||
|| {{{n_sta.sta_configure(bool}}}  || {{{n_sta.enable_beacon_mac_time_update(bool)}}} ||  [//docs/mango-wlan-exp/node.html#wlan_exp.node.WlanExpNode.enable_beacon_mac_time_update docs]  ||
|| {{{n_ibss.ibss_configure(bool}}}  || {{{n_ibss.enable_beacon_mac_time_update(bool)}}} ||  [//docs/mango-wlan-exp/node.html#wlan_exp.node.WlanExpNode.enable_beacon_mac_time_update 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.