API conceptsFULL_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 WFM_API_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 is able to 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 in order 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 WfmHiSetPmModeReq_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 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 thus 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. 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 practise, 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 client isolation is enabled, the access point will discard all data frames intended to 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 will switch to each channel to be scanned in turn and listen 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 solicitate 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 WfmHiSsidDef_t elements concatenated together.

In order 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 WfmHiSetArpIpAddressReq_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 WfmHiSetNsIpAddressReq_t message.

By default, the device will forward 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. In order to facilitate low-power use-cases, the device offers multiple options for discarding some of the received packets in the firmware.

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. In case 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 WfmHiAddMulticastAddrReq_t and WfmHiRemoveMulticastAddrReq_t messages.

Broadcast filtering

Broadcast filtering is a boolean option. When enabled, the device will discard 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 WfmHiSetBroadcastFilterReq_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 WfmHiConnectReq_t message. The various roaming parameters may be adjusted using WfmHiSetRoamParametersReq_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 deivce will not use even if they are allowed by the network.

The precise allowed rates may be adjusted using WfmHiSetTxRateParametersReq_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 then it will default to using only 1Mbits/sec rate.