wiki:802.11/wlan_exp/bss

802.11 Reference Design Experiments Framework Basic Service Set (BSS)

The 802.11 Reference design uses a structure to record information about a 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 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:

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.

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.

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 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 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 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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)
Last modified 18 months ago Last modified on Apr 8, 2016, 5:22:19 PM