{{{#!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 == === 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: {{{#!python >>> 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: {{{#!python >>> 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 [../examples 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. {{{#!th v1.4 }}} {{{#!th v1.5 }}} {{{#!th Notes }}} {{{#!tr valign=top {{{#!td align=center n/a }}} {{{#!td align=center {{{phy_mode}}} }}} {{{#!td 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}}}. }}} }}} {{{#!tr valign=top {{{#!td align=center {{{rate}}} }}} {{{#!td align=center {{{mcs}}} }}} {{{#!td 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.}}} }}} }}} {{{#!tr valign=top {{{#!td align=center {{{pkt_type}}} }}} {{{#!td align=center {{{pkt_type}}} }}} {{{#!td 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. }}} }}} {{{#!tr valign=top {{{#!td align=center {{{timestamp_frac}}} }}} {{{#!td align=center {{{timestamp_frac}}} }}} {{{#!td 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. }}} }}} === Removed Entry Types === The following entry types have been removed: * {{{BSS_INFO}}}: use [//docs/mango-wlan-exp/node.html#wlan_exp.node.WlanExpNode.get_bss_info n.get_bss_info()] and [//docs/mango-wlan-exp/node.html#wlan_exp.node.WlanExpNode.get_network_list n.get_network_list()] to retrieve BSS information from a node. * {{{STATION_INFO}}}: use [//docs/mango-wlan-exp/node.html#wlan_exp.node.WlanExpNode.get_station_info n.get_station_info()] to retrieve information about associated stations from a node * {{{COUNTS_TXRX}}}: use [//docs/mango-wlan-exp/node.html#wlan_exp.node.WlanExpNode.counts_get_txrx n.counts_get_txrx()] to retrieve Tx/Rx counts data from a node