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)
flags	BSS flags
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:

• ​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.

• ​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 if the node is a member of a BSS. This list could be empty.

• configure_bss() for ​AP, for ​STA, for ​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 user I/O documentation for each MAC project).

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

Changes to code from 802.11 Reference Design v1.4

• 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 but does not remove any entries from the BSS information list; wipes station_info list
      • n.reset(bss=True), unlike n.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, ...}

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)

Example: Reset

>>> n_ap.configure_bss(ssid='My Network', beacon_interval=100, channel=6, ht_capable=True)
>>> n_ap.add_association(n_sta1)
>>> n_ap.add_association(n_sta2)

# Clear STA1 station info and BSS
#     - Will send OTA disassociate packet to AP
>>> n_sta1.get_bss_info()
{'bssid': AP_WLAN_MAC_ADDR, 'ssid': 'My Network', 'beacon_interval': 100, 'channel': 6, 'ht_capable': True, ...}

>>> n_sta1.reset(bss=True)
>>> n_sta1.get_bss_info()
None

>>> 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
n.configure_bss(bssid=my_bss['bssid'], ssid=my_bss['ssid'], channel=my_bss['channel'], 
                beacon_interval=my_bss['beacon_interval'], ht_capable=my_bss['ht_capable'])