Introduction

The Wi-Fi FullMAC solution provides a standard wireless network interface for the host, allowing Wi-Fi applications (such as wpa_supplicant, TCP/IP stack, etc.) to run smoothly on the operating system.

The interfaces supported by Wi-Fi FullMAC are listed below：

Interface

Host (Operating system)

Linux

FreeRTOS

SDIO

Y

Y

SPI

Y

Y

USB full speed

Y

N

UART

TBD

TBD

The Wi-Fi FullMAC driver implements the following modules:

  • Provide a data transmission path between the host and the device based on a private transmission protocol via the SDIO/SPI interface

  • Adapt the cfg80211 layer and register the wireless network interface (wlan0/1) in the kernel to enable network data packet interaction between the Linux kernel and the RTL8721Dx

  • Provide commonly-used and proprietary commands to configure the parameters of Wi-Fi interface

To clarify, in the following sections, the term host refers to the Linux PC acting as the host, and the term device refers to the RTL8721Dx serving as the device.

../../../../_images/wifi_fullmac_architecture.svg

Wi-Fi FullMAC architecture

Features

Item

Detail

Description

Wi-Fi Mode

  • STA

  • SoftAP

  • NAN (Linux host only)

  • P2P GO (Linux host only)

  • The STA mode can coexist with any of the other three modes.

  • The SoftAP mode and NAN mode cannot coexist with P2P GO mode.

Protocal

802.11 b/g/n

Security

Open/WPA/WPA2/WPA3

Power Save

Wowlan
In the suspend state, the device can wake up to send and receive packets.
The host will only be awakened when the device receives a packet that
matches a predefined pattern, thereby achieving power saving.
Some filtering conditions (patterns) can be customized as needed, for
example, wakeup packet type, MAC address, IP address, or port, etc.

Proxy Offload:

  • ARP Response

  • mDNS

  • ICMP Response (TODO)

  • SNMP (TODO)

  • LLMNR (TODO)

  • SSDP/SLP/WSD/LLTD (TODO)
The host can offload some protocols to the device.
In the suspend state, when the device receives an offloaded protocol
request, it can handle the request autonomously and send a response
without waking up the host, thereby saving power.

File Tree

The Linux driver in the SDK is located at: {SDK}/component/wifi/cfg80211_fullmac/rtl8730e. The main focus should be on the files within the red boxes below.

../../../../_images/fullmac_driver_file_tree.svg

FullMAC driver file tree

Porting Guide

Hardware Configuration

SDIO

The SDIO FullMAC can be used on Linux PC with SDIO interface or Raspberry Pi. The following pins of RTL8721Dx are used for SDIO FullMAC function.

SDIO FullMAC used pins

RTL8721Dx pin

Raspberry Pi pin

Function

PB6

GPIO 26

SDIO_DAT2

PB7

GPIO 27

SDIO_DAT3

PB8

GPIO 23

SDIO_CMD

PB9

GPIO 22

SDIO_CLK

PB13

GPIO 24

SDIO_DAT0

PB14

GPIO 25

SDIO_DAT1

Linux PC

For the Linux PC, an SDIO host peripheral is required. Please connect to RTL8721Dx with the corresponding pins according to SDIO FullMAC used pins.

The RTL8721Dx can also use a gold finger adapter to convert the SDIO pins into a standard SD card, as the following figure shows, and supports the hardware platform only with an SD card slot. Note that in this case, you need to contact us to modify the demo board circuit.

../../../../_images/sdio_adapter_board.jpg

RTL8721Dx SDIO adapter board

Raspberry Pi

The pin location of RTL8721Dx demo board corresponds to the pin location of Raspberry Pi. In order to run at high speed, it’s strongly recommended to plug the demo board directly into Raspberry Pi, as the following figure shows.

The pins used for SDIO FullMAC on Raspberry Pi are listed in SDIO FullMAC used pins.

../../../../_images/connection_with_raspberry_pi.jpg

RTL8721Dx connection with Raspberry Pi

SPI

The SPI FullMAC can be used on on platforms with SPI interface, such as Raspberry Pi. The following pins of RTL8721Dx and Raspberry Pi are used for SPI FullMAC function.

SPI FullMAC used pins

RTL8721Dx pin

Raspberry Pi pin

Function

Description

PB24

GPIO 10

SPI_MOSI

SPI pins

PB25

GPIO 9

SPI_MISO

PB23

GPIO 11

SPI_CLK

PB26

GPIO 8

SPI_CS

PB8

GPIO 23

DEV_TX_REQ
An output pin for RTL8721Dx, used to indicate
to host that it has a data packet to send with a rising edge.

PB9

GPIO 22

DEV_READY
An output pin for RTL8721Dx, used to indicate its readiness
for SPI transcation to host.

  • 1: Device is ready.

  • 0: Device is busy.

Software Configuration

Device Driver

  1. Execute make menuconfig under the path {SDK}/amebadplus_gcc_project

    1. Click CONFIG Link Option > IMG2(Application) running on FLASH or PSRAM?, and select PSRAM

      ../../../../_images/sdio_config_flash_or_psram.png

    2. Click CONFIG WIFI > INIC Mode, select SDIO_FULLMAC for SDIO interface or SPI_FULLMAC for SPI interface, then select KM0 as WIFI Driver Location. If you have any other special requirements, select KM4 as WIFI Driver Location.

      ../../../../_images/wifi_sdio_spi_selection.png

  2. Execute the make command to generate km4_boot_all.bin and km0_km4_app.bin after the build is successfully complete.

  3. Use the Image Tool to flash the bin files to RTL8721Dx and restart the device.

Host Driver

The FullMAC driver has been tested and verified to work on Linux kernel versions 5.4 and 5.10. If you encounter any compilation errors on other kernel versions, please contact us.

  1. Prerequisites: install the following software packages on Linux system.

    sudo apt-get install build-essential
sudo apt install dhcpcd
sudo apt install hostapd
sudo apt install dhcpd

  2. Enable the SDIO or SPI function.

    • For Linux PC, skip this step.

    • For Raspberry Pi:

      • SDIO: Use dtoverlay command to configure SDIO. For the Raspberry Pi 4, type the following command:

        sudo dtoverlay sdio poll_once=off

      • SPI:

        1. Enable SPI peripheral

          sudo raspi-config

        2. Select Interface Options > SPI > Yes

        ../../../../_images/raspberry_pi_spi_config.png

        1. Generate and apply Device Tree Overlay

        sudo su
cd {driver_path}/cfg80211_fullmac/rtl8730e/spi
dtc -@ -Hepapr -I dts -O dtb -o inic_spidev.dtbo spidev-overlay.dts
cp inic_spidev.dtbo /boot/overlays/
dtoverlay inic_spidev

  3. Build the module

    1. In the path /component/wifi/cfg80211_fullmac/rtl8730e, execute the following script with an interface parameter to configure host driver.

      • SDIO:

        ./fullmac_setup.sh sdio

      • SPI:

        ./fullmac_setup.sh spi

    2. Copy the folder of cfg80211_fullmac to the Linux system.

    3. Open the terminal and execute the following command:

      cd {driver_path}/cfg80211_fullmac/rtl8730e;make

  1. Load the module.

    • SDIO: fullmac_sdio.ko is generated in /cfg80211_fullmac/rtl8730e/sdio.

      sudo su
cp sdio/fullmac_sdio.ko /lib/modules/XXX/
depmod
modprobe fullmac_sdio

    • SPI: fullmac_spi.ko is generated in /cfg80211_fullmac/rtl8730e/spi.

      sudo su
cp spi/fullmac_spi.ko /lib/modules/XXX/
depmod
modprobe fullmac_spi

    When loading module is successful, use ifconfig command to get the information of net device. The net device whose MAC address starts with 00:e0:4c is STA, and the net device whose MAC address starts with 00:e1:4c is softAP.

    The following is an example, in which wlan1 is STA and wlan2 is softAP.

    ../../../../_images/ifconfig_sta_softap.png

  2. Connect to STA.

    1. Create wpa_supplicant.conf under the path /etc/wpa_supplicant/ and add AP information.

      There is an example configuration for WPA2.

      ctrl_interface=/var/run/wpa_supplicant
network={
         ssid="HUAWEI-JX2UX5_HiLink_5G"
         psk="12345678"
}

    2. Connect with the following command:

      Wpa_supplicant -D nl80211 -i wlanX -c /etc/wpa_supplicant/wpa_supplicant.conf -dd > /var/wifi_log

    3. Obtain the IP address with the following command:

      dhcpcd wlanX

    Note

    • The wlanX in the above command refers to the name of STA obtained from Step 4.

    • The configuration files of OPEN and WPA3 are different, please refer to the official supplicant documentation for details.

    • For Ubuntu system, if you want to manually connect using command wpa_supplicant and obtain an IP address, first stop NetworkManager and DHCP service to avoid the influence of NetworkManager on wpa_supplicant.

      sudo su
systemctl stop NetworkManager
systemctl disable NetworkManager
systemctl stop dhcpcd.service

  3. Setup the softAP.

    1. Create hostapd.conf under the path /etc/hostapd/ and add the configuration information.

      Take WPA2 as an example, you can add the following information:

      driver=nl80211

logger_syslog=-1
logger_syslog_level=2
logger_stdout=-1
logger_stdout_level=2

ctrl_interface=/var/run/hostapd

hw_mode=g
channel=6
ssid=aaa_test
beacon_int=100
dtim_period=1
max_num_sta=8
rts_threshold=2347
fragm_threshold=2346

ieee80211n=1

erp_send_reauth_start=1

wpa=2
wpa_key_mgmt=WPA-PSK
wpa_pairwise=CCMP
wpa_passphrase=12345678

      Note

      This configuration file is applicable for WPA2 softAP. If you want to use OPEN or WPA3, please refer to the official hostapd documentation to set the parameters.

    2. Create udhcpd_wlanX.conf under the path /etc/ and add the following information:

      # The start and end of the IP lease block
start          192.168.43.20
end            192.168.43.254

# The interface that udhcpd will use
interface      wlanX

opt    dns     192.168.43.1 129.219.13.81
option subnet  255.255.255.0
opt    router  192.168.43.1
option domain  local
option lease   864000          # default: 10 days
option msstaticroutes  10.0.0.0/8 10.127.0.1           # single static route
option staticroutes    10.0.0.0/8 10.127.0.1, 10.11.12.0/24 10.11.12.1
option 0x08    01020304        # option 8: "cookie server IP addr: 1.2.3.4"

    3. Start the softAP.

      hostapd /etc/hostapd/hostapd.conf -i wlanX

    4. Set the IP address.

      ifconfig wlanX 192.168.43.1

    5. Start the DHCP server.

      udhcpd -f /etc/udhcpd_wlanX.conf

    Note

    The wlanX in the above command refers to the name of softAP obtained from Step 4.

Throughput

Interface

Wi-Fi driver location

Item

BW 20M (Mbps)

BW 40M (Mbps)

SDIO [1]

KM0

TCP RX

36

42

TCP TX

46

54

UDP RX

50

60

UDP TX

55

62

KM4 (331MHz)

TCP RX

41

58

TCP TX

46

80

UDP RX

53

74

UDP TX

53

90

SPI [2]

KM0

TCP RX

14.5

TCP TX

16

UDP RX

17.4

UDP TX

17.8

Note

  • [1] The data is the test result of device code running in PSRAM, host driver running on Dell Optiplex 3080 MT.

  • [2] The data is the test result of device code running in PSRAM, host driver running on Raspberry Pi 4.

Memory Size Requirement

Device

Take the Wi-Fi driver running on KM0 for an example:

Item

KM0

KM4

txt

270KB

31KB

rodata

51KB

9KB

data+bss

17KB

4KB

heap

~68KB

~2.5KB

Host

Host

Item

fullmac_xxx.ko

SDIO

txt

88KB

data

65KB

bss

18KB

SPI

txt

73KB

data

54KB

bss

18KB

Note

The characters before .ko are sdio or spi, corresponding to different hosts.