API concepts

FULL_MAC_API

Service Set Identifier (SSID) is an unique identifier of a Wi-Fi network that can be seen as a network name since it's typically an ASCII or UTF8 string.

SSID contains 0 to 32 bytes of data. When SSID is 0 bytes long, it's known as a broadcast SSID or a wildcard SSID.

Basic Service Set Identifier (BSSID) is an unique identifier of a Wi-Fi Access Point. BSSID is a 6-byte field set in the same format as an IEEE 802 MAC address.
See Media Access Control address for further details.

Broadcast MAC address

When all bytes of the MAC address field are set to 0xFF, the MAC address is considered to be a broadcast MAC address.

{ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF }

Multicast MAC address

When the lowest bit of the first byte is set, the MAC address is considered to be a multicast MAC address.

{ 0x33, 0x33, 0x00, 0x00, 0x00, 0x01 }

Zero MAC address

When all bytes of the MAC address field are set to 0x00, the MAC address is considered to be a zero MAC address.

{ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 }

802.11 Vendor-specific element starts with a 1-byte Element ID (0xDD), followed by 1-byte Element Length specifying the amount of bytes after the length field. The next field is Organization Identifier (OUI) field which is typically at least 3 bytes, followed by the vendor-specific content.

An example of a vendor-specific IE that uses a Silicon Laboratories OUI (90-FD-9F), a vendor-specific type of 0 and vendor-specific data "HELLO".

{ 0xDD, 0x09, 0x90, 0xFD, 0x9F, 0x00, 0x48 0x,45 0x4C, 0x4C, 0x4F }

Note that the Password element must always contain SL_WFX_PASSWORD_SIZE bytes. Only the bytes up to PasswordLength are considered to be valid, the rest are ignored.

An example of a 64-bit WEP key "12345" in ASCII format

{ 0x31, 0x32, 0x33, 0x34, 0x35 }

An example of a 64-bit WEP key "\x31\x32\x33\x34\x35" in HEX format

{ 0x33, 0x31, 0x33, 0x32, 0x33, 0x33, 0x33, 0x34, 0x33, 0x35 }

Received Channel Power Indicator (RCPI) is a monotonically increasing, logarithmic function of the received power level.

Value	Description
0	Power level is less than -109.5 dBm
1 - 219	Power level is between -109.5 dBm and 0 dBm
220	Power level is equal or greater than 0 dBm
221 - 255	Reserved

The following equation can be used to convert the RCPI value to corresponding dBm value.
[signal level in dBm] = (RCPI / 2) - 110
RCPI 60 => signal level is -80 dBm
RCPI 80 => signal level is -70 dBm

In Wi-Fi power management, a device has two power modes: active and power save. In active mode, the device can transmit and receive packets. When in power save, the device has signaled other devices it's available only periodically and communicating with it requires specific power management procedures.

Wi-Fi power management is different from device power management. Even when the device has enabled Wi-Fi power save, it doesn't necessarily mean the device is actually in a low-power state. Wi-Fi power save must be enabled to use device power management but not vice versa.

Wi-Fi power save is only available in Wi-Fi client role. The functionality can be controlled using sl_wfx_set_pm_mode_req_t message. The device has three different power management modes.

WFM_PM_MODE_ACTIVE

In this mode, the device does not use Wi-Fi power management. Since no special power management procedures are required, this mode gives the best throughput and latency. Device power management cannot be used in this mode. This is the default mode after the connection has been established.

WFM_PM_MODE_BEACON

In this mode, the device signals to the Wi-Fi Access Point it's in power save and therefore only available on periodic intervals. This causes the Access Point to buffer packets destined to the device until the device retrieves them and therefore causes extra delays on received packets. However, the mode allows the device to use device power management.

WFM_PM_MODE_DTIM

This mode is similar to WFM_PM_MODE_BEACON but it uses a different periodic interval called DTIM period. The length of the DTIM period depends on the access point used but it is at least as long as the period in WFM_PM_MODE_BEACON.

Usually, a Wi-Fi Access Point will advertise its details in Beacon frames as well as in Probe Response frames which are sent as a response to Probe Request frames. One of the details advertised is the SSID of the network.

When the network is hidden, the device will replace the actual SSID in Beacon frames with a broadcast SSID and will stop responding to Probe Requests that do not specify the correct SSID. In practice, other stations will still see there is a network near-by due to the Beacon frames but they will not be able to determine the SSID.

This feature shouldn't be seen as a security feature since it's fairly simple to determine the SSID by passively observing stations that know the correct SSID.

When a Wi-Fi network has multiple stations connected, they communicate with each other by first sending the data frame to the Access Point. Access Point then determines the destination is one of its clients and resends the frame to the destination station.

When the client isolation is enabled, the Access Point discards all data frames intended for other stations. Therefore, the stations will only be able to communicate with the access point.

Data frame with Ethernet II header

When transmitting and receiving data frames in this format, the payload message such as an IP packet or an ARP packet is encapsulated in an Ethernet II frame header without the trailing CRC checksum.

Ethernet II headers is 14 bytes (6-byte Destination MAC address, 6-byte Source MAC Address, 2-byte EtherType). The EtherType is written in big-endian format.

An ARP packet (EtherType 0x0806) sent to the broadcast address (FF:FF:FF:FF:FF:FF) from the source MAC address (00:01:02:03:04:05) therefore starts with the header

{ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x08, 0x06 }

and is immediately followed by the actual ARP packet.

Scan mode

The device supports two modes of scanning: active and passive. In passive mode, the device switches to each channel to be scanned in turn and listens for Access Points operating on the channel. After a time limit, it switches to the next channel.

The active mode is similar to the passive mode but in addition to listening, the device will solicit advertisements from the access points on the channel. Whether an Access Point responds to a solicitation depends on the SSID(s) used in the scan. If the scan is performed with a wildcard SSID, all access points on the channel will respond. If performed with a specific SSID, only the access points having that SSID will respond.

Note that even when scanning with a specific SSID, the scan results may contain other access points if the device happened to hear the advertisement while on the channel.

Specific channel list

It's possible to specify a list of channels to be scanned. The channel list is an array of bytes, one byte per channel. The channels are scanned in the order given.

An example of channels list (1, 6, 11)

{ 0x01, 0x06, 0x11 }

Specific SSID list

When performing an active scan, a list of SSIDs to be scanned can be specified. Only the SSIDs on the list will be queried. The lists consists of multiple sl_wfx_ssid_def_t elements concatenated together.

Scan Parameters

In the command sl_wfx_set_scan_parameters_req_t , it is possible to specify some scan parameters that will apply to every subsequent scan. It must be noted that parameters that do not comply with the current environment will be overridden internally (e.g., a very long scan that would jeopardize the current connection will be made shorter). In this case, a WFM_STATUS_WARNING will be issued in sl_wfx_start_scan_cnf_t . It is the advised that the host adjusts the scan parameters.

To facilitate low-power use-cases, there is a possibility to offload replying to Address Resolution Protocol (ARP) requests and IPv6 Neighbor Solicitation (NS) packets to the device. By default, the offloading functionality is disabled.

ARP offloading

When the functionality is enabled, the device will respond to ARP requests that specify one of the configured IPv4 addresses. The request is not forwarded to the host. The functionality can be controlled using sl_wfx_set_arp_ip_address_req_t message.

NS offloading

When the functionality is enabled, the device will respond to IPv6 NS packets that specify one of the configured IPv6 addresses. The request is not forwarded to the host. The functionality can be controlled using sl_wfx_set_ns_ip_address_req_t message.

By default, the device forwards all packets it receives from the network to the host. In a busy network, processing the broadcast and the multicast traffic may be a significant source of power consumption on the host. To facilitate low-power use-cases, the device offers multiple options for discarding some of the received packets on the device.

Multicast filtering

Filtering of multicast traffic is based on a whitelist of destination multicast addresses. Any received packet whose destination address does not match the whitelist is automatically discarded. If the host is not interested in multicast traffic, it's also possible to discard all multicast traffic. By default all multicast packets are accepted. The functionality can be controlled using sl_wfx_add_multicast_addr_req_t and sl_wfx_remove_multicast_addr_req_t messages.

Broadcast filtering

Broadcast filtering is a boolean option. When enabled, the device discards all received packets sent to the broadcast address except ARP and DHCP messages. By default, all broadcast packets are accepted. The functionality can be controlled using sl_wfx_set_broadcast_filter_req_t message.

When operating in Wi-Fi client role, the device is capable of autonomously switching to a different access point when the current access point is either lost or the signal strength drops below the roaming threshold. The device will only consider access points that have the same SSID and that otherwise have the same security capabilities as the previous access point.

The autonomous roaming functionality can be disabled by setting the corresponding option in sl_wfx_connect_req_t message. The various roaming parameters may be adjusted using sl_wfx_set_roam_parameters_req_t message. Parameter changes will be applied at the next connection.

A Wi-Fi device may use a number of different data rates for transmission. When operating as a client, a device adapts the rates it uses to match those the access point authorizes. However it is possible to specify rates that the device will not use even if they are allowed by the network.

The precise allowed rates may be adjusted using sl_wfx_set_tx_rate_parameters_req_t message. Parameter changes will be applied at the next connection. If no overlap between these parameters and the access point's supported rates list is found, it will default to using only 1Mbits/sec rate.