Instruction on how to use wireless WoL (Wake on LAN) using RTL8189FS (RTL8189FTV) module

[Deoptim]

Instruction on how to use wireless WoL (Wake on LAN) using RTL8189FS example in Armbian 23.x Bookworm
(This wireless WIFI adapter is installed in Oprange Pi Lite/Oprange Pi Plus(2E)/Orange Pi Zero Plus/Oprange Pi PC Plus/Oprange Pi 2/etc...)

 

1. First of all we need to change the device tree configuration file dts file for our single board. The point is that for most WIFI drivers for SDIO interface there is a normal configuration of single board wake-up via interrupt and therefore there is no need to go into dts. In the driver for RTL8189FS (aka RTL8189FTV) there is NO such feature as "host-wake" interrupt and we will have to make small changes to wake up the single board when Magic packet (WoL) is detected through the "gpio-keys" button module.

The same method will most likely work for the related RTL8189ES (aka RTL8189ETV) adapter, but keep in mind that here you will most likely need other settings in the dts file, since the gpios (for wifi_rst and wifi_wake) for your single-board adapter will be under a different number.

 

Скрытый текст

1.1. Copy the attached file without txt extension somewhere on the single board dir.

(note that here the sw4 (or Power) button configuration is additionally fixed to allow safe shutdown/wakeup of the device, since some time ago this option was broken in new kernels).

 

1.2. Regarding the same path where our dts file is, create a dtbo file:

sudo dtc -@ -I dts -O dtb -o /boot/dtb/overlay/sun8i-h3-wol-wakeup-for-rtl8189fs.dtbo wol-wakeup-for-rtl8189fs.dts

 

1.3. Activate System->Hardware->wol-wakeup-for-rtl8189fs our created profile via armbian-config:

sudo armbian-config

 

Click Save then Back, in the window agree to Reboot

 

1.4. After rebooting the suspend mode of these devices should work properly, because the KEY_POWER and keep-power-in-suspend options were missing, you can check the suspend mode with the command:

sudo systemctl suspend

(keep in mind that the power/wake button must work properly to wake up the single board, but we should have already fixed this problem with our dtbo configuration file)

 

2 The second step is to compile and install a new driver for RTL8189FS with WoL function enabled, I will do it on the single board itself. You can also do cross compilation (do it on your computer).

 

Скрытый текст

2.1. Install dependencies:

sudo apt update
sudo apt install git build-essential dkms linux-headers-current-sunxi

 

2.2. Clone the driver repository, go to a convenient folder in advance, I do it directly in ~/ directory:

git clone https://github.com/jwrdegoede/rtl8189ES_linux -b rtl8189fs
cd rtl8189ES_linux

 

2.3. Do the replacement in Makefile, note you can also manually edit say in nano and put "=y" for these options, but I will use sed:

sed -i 's/CONFIG_WOWLAN = n/CONFIG_WOWLAN = y/' Makefile
sed -i 's/CONFIG_GPIO_WAKEUP = n/CONFIG_GPIO_WAKEUP = y/' Makefile
sed -i 's/CONFIG_RTW_DEBUG = y/CONFIG_RTW_DEBUG = n/' Makefile

 

2.4. Now before compiling we need to make sure we have a path (after installing linux-headers-current-sunxi):

ls /lib/modules/$(uname -r)/build

And also need the full path (starting from /) where the rtl81899ES_linux sources folder is located.

 

2.5. Now compile the driver:

make ARCH=arm -C /lib/modules/$(uname -r)/build M=/home/deoptim/rtl8189ES_linux modules -j4

(note that the path of the rtl81899ES_linux src here is my path, you should replace it with your own)

 

2.6. After successful compilation and before installing the driver, make a backup copy of the existing 8189fs.ko module:

sudo mv /lib/modules/$(uname -r)/kernel/drivers/net/wireless/rtl8189fs/8189fs.ko /lib/modules/$(uname -r)/kernel/drivers/net/wireless/rtl8189fs/8189fs._

 

2.7. You can now install the driver:

sudo make install MODDESTDIR=/lib/modules/$(uname -r)/kernel/drivers/net/wireless/rtl8189fs/

 

2.8. Add additional parameters to module config file (when it firs time load module at boot process) to /etc/modprobe.d/8189fs.conf file and again, I use sed:

sudo sed -i 's/options 8189fs rtw_power_mgnt=0 rtw_enusbss=0/options 8189fs rtw_power_mgnt=0 rtw_enusbss=0 rtw_wakeup_event=0x5 rtw_wowlan_sta_mix_mode=0x1/' /etc/modprobe.d/8189fs.conf

(there are details about the important rtw_wakeup_event parameter in the "Additionally" section)

 

2.9. Now you can already reboot the single board, which is highly recommended. Or hot-swap the module with a command(without reboot):

sudo modprobe -r 8189fs && sudo modprobe 8189fs

 

Скрытый текст

To restore the original module:

sudo mv /lib/modules/$(uname -r)/kernel/drivers/net/wireless/rtl8189fs/8189fs._ /lib/modules/$(uname -r)/kernel/drivers/net/wireless/rtl8189fs/8189fs.ko
sudo /sbin/depmod -a
sudo modprobe -r 8189fs && sudo modprobe 8189fs

 

 

 

3. How to use WoL.

 

Скрытый текст

3.1. The first physical device phy0 is used to detect WoL, for example the command "iw dev" gives us the following list:

deoptim@homeassistant:~$ iw dev
phy#1
        Interface wlan1
                ifindex 3
                wdev 0x100000001
                addr 02:81:e1:xx:xx:xx
                type managed
                txpower 12.00 dBm
phy#0
        Interface wlan0
                ifindex 2
                wdev 0x1
                addr 02:81:e1:xx:xx:xx
                ssid Apple Network XXXXXX
                type managed
                txpower 12.00 dBm
deoptim@homeassistant:~$

So the first interface we have wlan0 (for the device phy#0), pay attention and memorize or write down the mac addr for it (not from this list address, but your configuration of course ), it is at this address we will wake up single board and it is from the interface wlan0 need to connect to the router or access point.

 

3.2. In order for the WoL mode to work, you need to enable it with the option (as in this instruction😞

sudo iw phy0 wowlan enable any

(note, if you want to use WoL permanently, this procedure should be repeated every time you boot the system, for example, write a command in the /etc/rc.local file, also other options than "any" for this RTL8189FS driver do not work, the rtw_wakeup_event module parameter is used to filter a specific event (more details in the "Additionally" section). For example, to disable WoL you should change the enable value in the same iw utility parameter to "wowlan disable".)

 

3.3. Now if we put our single board into sleep mode with the command:

sudo systemctl suspend

We will see that the single board has fallen asleep without disconnecting from the router or access point. Now if you try to wake it up using any standard WoL utility (for example for Windows, or use wakeonlan for Linux), the single board will wake up.

 

4. Additionally.
 

Скрытый текст

4.1. Disadvantages and restrictions relate to the fact that the system uses two interfaces wlan0 and wlan1 - there are cases when a single board connected as a client swaps these interfaces for this connection.
If an access point (Hotspot) is used as the second interface - there may be configuration problems and wakeup will not work properly. So it is advisable to either NOT use the second interface (maybe even disable it at the compilation stage) or if the second interface is used - disable wlan1 before starting the service "sudo systemctl suspend" and bring it up again after waking up.
upd: In my case I got out of the problem with this script /lib/systemd/system-sleep/my_script (give chmod +x exec permissions):

#!/bin/sh
case $1/$2 in
  pre/*)
    echo "Going to $2..."
    systemctl stop watchdog.service
    if [ $(nmcli -f GENERAL.STATE dev show wlan0 | sed 's/.*\s//') != "(connected)" ]
    then
      nmcli dev con wlan0
      sleep 5
    fi
    ;;
  post/*)
    echo "Waking up from $2..."
    systemctl start watchdog.service
    ;;
esac

 

4.2. The rtw_wakeup_event module parameter in the /etc/modprobe.d/8189fs.conf file configures the event at which the WIFI module wakes up the single board can be the following parameters:

/*
 * bit[0]: magic packet wake up
 * bit[1]: unucast packet(HW/FW unuicast)
 * bit[2]: deauth wake up
 */

Accordingly, we used 0x5 (bit[0] and bit[2]) to filter magic packet and deauth (if we get disconnected from the access point, we need to wake up - otherwise we can't). You can choose the parameter for your needs individually or all at once. In the source code 0x7 was used by default (all bits were selected), but in this case ?false? triggering is possible, in practice it looked like unexpected waking up almost immediately after falling asleep.

 

4.3. Sometimes Magic packet is not enough and we need to use event Deauth (disconnecting from the access point) - the point is that we are not always sure that the router or access point is OK and it will not disconnect itself or drop our connection. In this case, if SBC waking up from WoL is important, it is important for the single board to track which event wake it up, for example: if it were wake-up by event Deauth => then check if we are connected to the access point again => go back to suspend after a pause. If it were wake-up by event Magic Packet, then perform other actions.....
In this case, the wake-up event identifier via the WoL utility will help that's where it is in the driver:

deoptim@homeassistant:~$ cat /proc/net/rtl8189fs/wlan0/wowlan_last_wake_reason
last wake reason: 0x25
deoptim@homeassistant:~$

 

Here is an example where I rebooted my router (the options in rtw_wakeup_event were bit0 and bit2):

deoptim@homeassistant:~$ cat /proc/net/rtl8189fs/wlan0/wowlan_last_wake_reason
last wake reason: 0x10
deoptim@homeassistant:~$

 

Here are the possible values from the sources:

typedef enum _WAKEUP_REASON{
	RX_PAIRWISEKEY					= 0x01,
	RX_GTK							= 0x02,
	RX_FOURWAY_HANDSHAKE			= 0x03,
	RX_DISASSOC						= 0x04,
	RX_DEAUTH						= 0x08,
	RX_ARP_REQUEST					= 0x09,
	FW_DECISION_DISCONNECT			= 0x10,
	RX_MAGIC_PKT					= 0x21,
	RX_UNICAST_PKT					= 0x22,
	RX_PATTERN_PKT					= 0x23,
	RTD3_SSID_MATCH					= 0x24,
	RX_REALWOW_V2_WAKEUP_PKT		= 0x30,
	RX_REALWOW_V2_ACK_LOST			= 0x31,
	ENABLE_FAIL_DMA_IDLE			= 0x40,
	ENABLE_FAIL_DMA_PAUSE			= 0x41,
	RTIME_FAIL_DMA_IDLE				= 0x42,
	RTIME_FAIL_DMA_PAUSE			= 0x43,
	RX_PNO							= 0x55,
	AP_OFFLOAD_WAKEUP				= 0x66,
	CLK_32K_UNLOCK					= 0xFD,
	CLK_32K_LOCK					= 0xFE
}WAKEUP_REASON;

 

(for some reason 0x25 is not in the list, strange..... upd: the WolOn utility on Android unexpectedly gave another correct output as 0x21, i.e. the output still depends on the utility you use, I remind you that 0x25 is a Windows WoL utility).

 

By the way, we can change the wow_wakeup_event parameter (aka rtw_wakeup_event) on the fly, so we don't need to reboot the module if we need to do it quickly:

sudo sh -c 'echo 5 > /proc/net/rtl8189fs/wlan0/wow_wakeup_event'

 

4.4. It is also possible to wake-up a single board by event Pattern - it will wake-up when a packet with possible such patterns is sent (detailed instructions😞

/*
* IP filter This pattern if for a frame containing a ip packet:
* AA:AA:AA:AA:AA:AA:BB:BB:BB:BB:BB:BB:CC:CC:DD:-:-:-:-:-:-:-:-:EE:-:-:FF:FF:FF:FF:GG:GG:GG:GG:HH:HH:II:II
*
* A: Ethernet destination address
* B: Ethernet source address
* C: Ethernet protocol type
* D: IP header VER+Hlen, use: 0x45 (4 is for ver 4, 5 is for len 20)
* E: IP protocol
* F: IP source address ( 192.168.0.4: C0:A8:00:2C )
* G: IP destination address ( 192.168.0.4: C0:A8:00:2C )
* H: Source port (1024: 04:00)
* I: Destination port (1024: 04:00)
*/

 

This pattern is put in directly by the iwpriv utility (not iw for this driver, I repeat, only the "any" option works here), for example:

sudo iwpriv wlan0 wow_set_pattern pattern=-:-:-:-:-:-:-:-:-:-:-:-:08:00:45:-:-:-:-:-:-:-:-:06:-:-:0A:00:01:F6:-:-:-:-:13:C5:-:-

(where :08:00:  is Internet Protocol version 4 (IPv4) and :06:  is Reserved for DoD IP)

 

To clear a pattern, you must use the command:

sudo iwpriv wlan0 wow_set_pattern clean

 

You can find out whether the current pattern is written to the driver (or not) by command:

cat /proc/net/rtl8189fs/wlan0/wow_pattern_info

 

When the single board wakes-up on the current pattern, there will be this value:

deoptim@homeassistant:~$ cat /proc/net/rtl8189fs/wlan0/wowlan_last_wake_reason
last wake reason: 0x23
deoptim@homeassistant:~$

 

 

4.5. The number of wake-up's or interrupt statistics for a given wake-up (for each core) for the entire single board operation (before power off/reboot) can be viewed with the command:

deoptim@homeassistant:~$ cat /proc/interrupts  | grep wifi-host-wakeup
 83:          4          0          1          0  sunxi_pio_edge  42 Edge      wifi-host-wakeup
deoptim@homeassistant:~$

 

 

wol-wakeup-for-rtl8189fs.dts.txt

QuickStartGuideforWOW.399483868.pdf

Link to original source

Edited January 27 by Deoptim
Add info how to usage pattern