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

[[TracNav(802.11/TOC)]]

= 802.11 Reference Design Experiments Framework Basic Service Set (BSS) =

The 802.11 Reference design uses a structure to record information about a [https://en.wikipedia.org/wiki/Service_set_(802.11_network) basic service set (BSS)].  This information can be for the node's current BSS (i.e. network) or networks that the node has seen by either receiving a beacon or from [http://warpproject.org/docs/mango-wlan-exp-dev/node.html#network-scan scanning for networks].  Each node is either a member of no BSS (colloquially "unassociated") or a member of one BSS.  The following fields are recorded in the BSS information structure to describe a BSS:

||=  Field Name  =||=  Description  =||
|| bssid || BSS ID ||
|| channel || Primary channel ||
|| channel_type || Channel Type ||
|| ssid || SSID (32 chars max) ||
|| latest_beacon_rx_time || Value of System Time in microseconds of last beacon Rx ||
|| latest_beacon_rx_power || Last observed Rx Power (dBm) ||
|| capabilities || Supported capabilities of the BSS ||
|| beacon_interval || Beacon interval - In time units of 1024 us ||


=== Python ===

The 802.11 Reference Design Experiments Framework provides methods to interact with BSS information.  In addition to the fields above, the BSS information structures in Python also contain a {{{timestamp}}} field which is the value of the MAC time in microseconds when the structure was requested from the node.  The following methods are used to interact with BSS information:

  * [http://warpproject.org/docs/mango-wlan-exp-dev/node.html#wlan_exp.node.WlanExpNode.get_bss_info get_bss_info()]

     This method will return the BSS information about the node's current BSS.  The value returned can be {{{None}}} if the node is not a member of a BSS.

  * [http://warpproject.org/docs/mango-wlan-exp-dev/node.html#wlan_exp.node.WlanExpNode.get_network_list get_network_list()]

    This method will return a list of BSS information about all the networks that the node has seen.  This list can include the node's current BSS.  This list could be empty.

  * '''{{{configure_bss()}}}''' for [http://warpproject.org/docs/mango-wlan-exp-dev/node_ap.html#wlan_exp.node_ap.WlanExpNodeAp.configure_bss AP], for [http://warpproject.org/docs/mango-wlan-exp-dev/node_sta.html#wlan_exp.node_sta.WlanExpNodeSta.configure_bss STA], for [http://warpproject.org/docs/mango-wlan-exp-dev/node_ibss.html#wlan_exp.node_ibss.WlanExpNodeIBSS.configure_bss IBSS]
      
    This method will configure the node's current BSS.  For each node type, there is a specific implementation of {{{configure_bss}}} that has different argument requirements.  See below for more details.



=== Configuring the BSS ===

A node requires a minimum set of information to be a member of a BSS. The minimum set of information is:
   * BSSID: 48-bit MAC address
   * Channel: logical channel for Tx/Rx by BSS members
   * SSID: variable length string
   * Beacon Interval: time between TBTTs in units of TUs (not required by STA)

A node's current BSS can be populated by default in C, by active scanning, or by wlan_exp.  The DIP switch on the WARP v3 node can be used to control the default BSS at boot (see [http://warpproject.org/trac/wiki/802.11/Usage/UserIO user I/O documentation] for each MAC project).

It is possible to leave a BSS by nullifying the node's BSS state (e.g. {{{node.configure_bss(None)}}} or {{{node.reset(bss=True)}}}; see below for more information on the differences between these commands).  For STA and IBSS, nullifying the node's BSS state does not affect the network itself (i.e. the network does not go away just because the STA or IBSS node leaves the network).  However, for APs, nullifying the BSS state, means that the network no longer exists.  Therefore, for the AP the BSS will be removed from the network list, but will not be removed for the STA or IBSS.

'''Arguments:'''

 * {{{bssid}}}: depends on node type; {{{None}}} means to remove all BSS state; {{{False}}} means no change
  * '''AP''': must be node's wireless MAC address; A value of {{{False}}} will default to the node's wireless MAC address.
  * '''STA''': must be BSSID of BSS with which to associate
  * '''IBSS''': must be valid locally-administered BSSID (use [http://warpproject.org/docs/mango-wlan-exp-dev/wlan_exp_util.html#wlan_exp.util.create_locally_administered_bssid create_locally_administered_bssid()] utility to create locally-administered BSSIDs from MAC addresses)
 * {{{ssid}}}: string; {{{None}}} means no change
 * {{{beacon_interval}}}: integer in ![10, 65534]; {{{None}}} means no beacon Tx; {{{False}}} means no change
 * {{{channel}}}: Integer channel index; {{{None}}} means no change
 * {{{ht_capable}}}: Does the node advertise HT processing capabilities; {{{None}}} means no change

'''Default Values:'''

  * Default BSS at boot (if configured by user I/O):
    * The default BSS uses values defined at the top of each high-level MAC project (i.e. AP, STA, or IBSS):
      * {{{static char default_AP_SSID[]}}}
      * {{{#define WLAN_DEFAULT_BEACON_INTERVAL_TU}}}
      * {{{#define WLAN_DEFAULT_CHANNEL}}}
      * {{{#define WLAN_DEFAULT_USE_HT}}}
        * This parameter will affect both the BSS capabilities as well as the PHY mode of the default unicast TX parameters at boot.

   * When configuring BSS from Null to non-Null state:
     * {{{ht_capable}}} is not required for any high-level MAC project.  If it is not provided as an argument, then it will take on the default value specified by {{{#define WLAN_DEFAULT_USE_HT}}} (note: this will not affect the unicast TX parameters).
     * {{{beacon_interval}}} is not required for the STA MAC project.  If it is not provided as an argument, then it will get a default value.  If the network has not been seen, the default value will be {{{65535}}}.  If the network has been seen, then the default value will be the whatever value was taken from the beacon.


=== Changes to code from 802.11 Reference Design v1.4 ===

  * '''{{{configure_bss()}}} Replaces:'''
    * {{{node.set_channel()}}}: New method [http://warpproject.org/docs/mango-wlan-exp-dev/node.html#wlan_exp.node.WlanExpNode.set_radio_channel set_radio_channel()] only affects hardware, not BSS
    * {{{node_ap.get/set_ssid()}}}: Use {{{get_bss_info()}}} as getter
    * {{{node_ap.get/set_beacon_interval()}}}: Use {{{get_bss_info()}}} as getter
    * {{{node_sta.set_association()}}}
    * {{{node_ibss.join()}}}
    * {{{util.create_bss_info()}}}

  * '''Affected:'''
    * {{{node.reset()}}} has new arguments:
      * {{{bss=bool}}}: nullifies the node's BSS state and wipes station_info list
        * {{{node.reset(bss=True)}}}, unlike {{{node.configure_bss(bssid=None)}}}, shall produce the following OTA transmission:
          * For AP, a deauthentication frame to each associated station
          * For STA, a disassociation frame to its AP
          *  For IBSS, nothing. {{{n_ibss.reset(bss=True)}}} == {{{n_ibss.configure_bss(bssid=None)}}}
      * {{{network_list=bool}}}: wipes the node's list of overheard BSS information, excluding the bss_info entry for the node's current network (if any)
      * Removed arguments {{{associations=bool}}}, {{{bss_info=bool}}}
    * {{{node.reset_all()}}} includes {{{(bss=True, network_list=True)}}}


=== Example: Configuring BSS ===

{{{#!python
# Setup a new network with 1 AP, 1 STA
#     - Assumes that both nodes started with no default BSS 
>>> n_ap.configure_bss(ssid='My Network', beacon_interval=100, channel=6, ht_capable=True)
>>> n_ap.get_bss_info()
{'bssid': AP_WLAN_MAC_ADDR, 'ssid': 'My Network', 'beacon_interval': 100, 'channel': 6, 'ht_capable': True, ...}

>>> n_sta.get_bss_info()
None

>>> n_ap.add_association(n_sta)
>>> n_sta.get_bss_info()
{'bssid': AP_WLAN_MAC_ADDR, 'ssid': 'My Network', 'beacon_interval': 100, 'channel': 6, 'ht_capable': True, ...}
}}}

'''Observations:'''
  * For {{{n_ap.configure_bss( ... )}}}, since {{{bssid}}} was not specified and because this was an AP, the {{{bssid}}} defaulted to the {{{wlan_mac_address}}} of the node (i.e. {{{n_ap.wlan_mac_address}}}).
  * For {{{n_ap.configure_bss( ... )}}}, since {{{ht_capable}}} was specified, it was set to the provided value.  However, if {{{ht_capable}}} had not been specified, then it would have been set to a default value based on {{{#define WLAN_DEFAULT_USE_HT}}} in wlan_mac_ap.c.  If {{{WLAN_DEFAULT_USE_HT}}} was {{{0}}}, the default value would have been {{{False}}}.  If {{{WLAN_DEFAULT_USE_HT}}} was {{{1}}}, the default value would have been {{{True}}}.
  * The {{{n_ap.add_association(n_sta)}}} command will make sure that the STA adopts all the BSS information from the AP.


=== Example:  Changing Channel ===

{{{#!python
# Re-tune both nodes by adjusting the BSS channel
#     - Assumes both AP and STA are already part of a BSS
>>> for n in [n_ap, n_sta]:
...     n.configure_bss(channel=7)
}}}

=== Example:  Adjusting Beacon Interval ===

{{{#!python
# Update the beacon interval
#     - Assumes both AP and STA are part of a BSS
>>> n_ap.configure_bss(beacon_interval=250)
>>> n_ap.get_bss_info()
{'bssid': AP_WLAN_MAC_ADDR, 'ssid': 'My Network', 'beacon_interval': 250, 'channel': 6, 'ht_capable': True, ...}

# Query STA before it receives a new beacon
>>> n_sta.get_bss_info()
{'bssid': AP_WLAN_MAC_ADDR, 'ssid': 'My Network', 'beacon_interval': 100, 'channel': 6, 'ht_capable': True, ...}

# Query STA after it receives a new beacon
>>> time.sleep(250*1024*1e-6)
>>> n_sta.get_bss_info()
{'bssid': AP_WLAN_MAC_ADDR, 'ssid': 'My Network', 'beacon_interval': 250, 'channel': 6, 'ht_capable': True, ...}

# Disable AP beacon Tx
>>> n_ap.configure_bss(beacon_interval=None)

# When beacons are disabled, the STA will not receive any new information to update 
# beacon interval.  Therefore, it will retain its previous value.
>>> n_sta.get_bss_info()
{'bssid': AP_WLAN_MAC_ADDR, 'ssid': 'My Network', 'beacon_interval': 250, 'channel': 6, 'ht_capable': True, ...}
}}}

=== Example: Configuring IBSS ===

{{{#!python
# Setup an IBSS network for all IBSS nodes
bssid = util.create_locally_administered_bssid(node1.wlan_mac_address)

>>> for n in ibss_nodes:
...    n.configure_bss(bssid=bssid, ssid='WARP-IBSS', beacon_interval=100, channel=6)

# Change the IBSS network beacon interval
>>> for n in ibss_nodes:
...    n.configure_bss(beacon_interval=250)

# Disable beacon Tx by all but the first node
>>> for n in ibss_nodes[1:]:
...    n.configure_bss(beacon_interval=None)
}}}

'''Observations:'''
  * When setting up the IBSS network for all IBSS nodes, since {{{ht_capable}}} was not specified as part of the {{{n.configure_bss(bssid=bssid, ...)}}}, {{{ht_capable}}} for the BSS was set to a default value based on the value of {{{WLAN_DEFAULT_USE_HT}}} on each node.  Each IBSS node will use this value to construct its beacons.  Therefore, if there are different values, then there will be some beacons for the network that advertise HT capabilities and other beacons that do not advertise HT capabilities.


=== Example:  Reset AP ===

{{{#!python
# Set up AP
#   - Assume no other networks have been heard; no default boot network
#
>>> n_ap.configure_bss(ssid='My Network', beacon_interval=100, channel=6)
>>> n_ap.get_network_list()
[{'bssid': AP_WLAN_MAC_ADDR, 'ssid': 'My Network', 'beacon_interval': 100, 'channel': 6, ...}]

# Reset AP
#     - BSS state will be nullified
#     - BSS will be removed from network list, since it no longer exists
#
>>> n_ap.reset(bss=True)
>>> n_ap.get_bss_info()
None

>>> n_ap.get_network_list()
[]
}}}


=== Example:  Reset STA ===

{{{#!python

# Set up AP with two STA
#     - Assume no other networks have been heard; no default boot network
#
>>> n_ap.configure_bss(ssid='My Network', beacon_interval=100, channel=6)
>>> n_ap.add_association(n_sta1)
>>> n_ap.add_association(n_sta2)

# Look at current network state:
#    - STA 1 BSS information
#    - STA 1 Network List
#    - AP station info list
#
>>> n_sta1.get_bss_info()
{'bssid': AP_WLAN_MAC_ADDR, 'ssid': 'My Network', 'beacon_interval': 100, 'channel': 6, ...}

>>> n_sta1.get_network_list()
[{'bssid': AP_WLAN_MAC_ADDR, 'ssid': 'My Network', 'beacon_interval': 100, 'channel': 6, ...}]

>>> n_ap.get_station_info()
[{'mac_addr': STA1_MAC_ADDR, 'AID': 1, ...},
 {'mac_addr': STA2_MAC_ADDR, 'AID': 2, ...}]

# Reset BSS for STA1
#     - BSS state will be nullified
#     - Network list will not be modified
#     - Will send OTA disassociate packet to AP so STA1 is no longer in station info list
#
>>> n_sta1.reset(bss=True)
>>> n_sta1.get_bss_info()
None

>>> n_sta1.get_network_list()
[{'bssid': AP_WLAN_MAC_ADDR, 'ssid': 'My Network', 'beacon_interval': 100, 'channel': 6, ...}]

>>> n_ap.get_station_info()
[{'mac_addr': STA2_MAC_ADDR, 'AID': 2, ...}]
}}}

=== Example:  Scanning for Networks ===

{{{#!python
# To perform a scan using the current scan parameters, get the 
# resulting network list and restore the current BSS:

my_bss = n.get_bss_info()             # Get current BSS info
n.configure_bss(None)                 # Set BSS info to None
n.start_network_scan()                # Start network scan
time.sleep(5)                         # Wait for node to scan
n.stop_network_scan()                 # Stop network scan
networks = n.get_network_list()       # Get networks seen in scan
                
# Restore BSS
if (my_bss['capabilities'] & my_bss.get_consts().capabilities.HT_CAPABLE):
    ht_capable = True
else:
    ht_capable = False

n.configure_bss(bssid=my_bss['bssid'], ssid=my_bss['ssid'], channel=my_bss['channel'], 
                beacon_interval=my_bss['beacon_interval'], ht_capable=ht_capable)
}}}