2023-09-27 01:04:53 +00:00
# wake on wireless LAN
# developed for the PinePhone (rtl8723cs), but may work on other systems.
# key info was found from this chat between Peetz0r and megi: <https://irclog.whitequark.org/linux-sunxi/2021-02-19>
2023-10-08 00:00:26 +00:00
# additionally in the Realtek "Quick Guide For Wake on WLAN": <https://gist.github.com/Peetz0r/bf8fd93a60962b4afcf2daeb4305da40#file-quick_start_guide_for_wow-pdf>
# megi's devlog which enabled WOWLAN: <https://xnux.eu/log/031.html>
# driver lives in Megi's kernel tree, at drivers/staging/rtl8723cs/Makefile
2023-09-27 01:04:53 +00:00
#
# wowlan configuration can be inspected with:
# - `iw phy0 wowlan`
# - `cat /proc/net/rtl8723cs/wlan0/wow_pattern_info`
# - the "pattern mask" is a bitfield, where each bit `i` indicates if the "pattern content" byte at index `i` must match, or should be treated as Don't Care (`-`)
#
# wakeup sources can be monitored with:
# - `cat /proc/interrupts | rg rtw_wifi_gpio_wakeup`
# - e.g. `cat /sys/kernel/irq/25/actions` (if the above points to irq 25)
2023-09-27 01:30:06 +00:00
#
# caveats:
# - can take 15s or more from when the packet is broadcast to when an application services it.
# - WiFi doesn't respond to arp queries, so the sender might not actually know how to route
# the packet to WiFi device at all.
2023-10-08 00:00:26 +00:00
# - run `arp -s <ip-addr> <mac-addr>` on the sender to hardcode an arp association.
# - driver Makefile mentions ARP support though:
# - #bit3: ARP enable, bit2: deauth, bit1: unicast, bit0: magic pkt.
# - CONFIG_WAKEUP_TYPE = 0xf
# - CONFIG_IP_R_MONITOR = n #arp VOQ and high rate
# - #bit0: disBBRF off, #bit1: Wireless remote controller (WRC)
# - CONFIG_SUSPEND_TYPE = 0 (i think this is correct)
# - CONFIG_LPS_MODE = 1 (setting to 0 would disable LPS)
# - maybe ARP gets disabled as part of the power saving features (iw phy ... power-save; CONFIG_POWER_SAVING=y)?
2023-09-27 01:32:50 +00:00
# - packet matching happens below the OS, so it's not generic over virtual network devices like tunnels.
# Wake On Lan with a VPN effectively requires that you wake on *every* packet routed via that VPN
# since the meaning within any packet isn't obvious to the chipset.
2023-10-07 21:29:55 +00:00
#
# known problems:
# - may fail to wake on LAN, with the following signature after power-button wake:
# ```
# wpa_supplicant: wlan0: CTRL-EVENT-DISCONNECTED bssid=xx:xx:xx:xx:xx:xx reason=6
# wpa_supplicant: wlan0: Trying to associate with xx:xx:xx:xx:xx:xx (SSID='xx' freq=2437 MHz)
# wpa_supplicant: wlan0: CTRL-EVENT-REGDOM-CHANGE init=CORE type=WORLD
# wpa_supplicant: wlan0: CTRL-EVENT-STARTED-CHANNEL-SWITCH freq=2437 ht_enabled=1 ch_offset=0 ch_width=20 MHz cf1=2437 cf2=0
# wpa_supplicant: wlan0: Associated with xx:xx:xx:xx:xx:xx
# wpa_supplicant: wlan0: CTRL-EVENT-SUBNET-STATUS-UPDATE status=0
# wpa_supplicant: wlan0: WPA: Key negotiation completed with xx:xx:xx:xx:xx:xx [PTK=CCMP GTK=CCMP]
# wpa_supplicant: wlan0: CTRL-EVENT-CONNECTED - Connection to xx:xx:xx:xx:xx:xx completed [id=0 id_str=]
# ```
# - observed after a suspension of 67 minutes.
# - WiFi chip *should* have a way to wake on connection state change, i just need to enable it?
2023-10-07 21:51:33 +00:00
# - `iw phy phy0 wowlan enable disconnect` => Invalid argument (-22)
# - `iw phy0 wowlan enable net-detect ...` (from man example) => Operation not supported (-95)
2023-10-08 00:00:26 +00:00
# - Realtek Quick Start guide claims "CONFIG_WAKEUP_TYPE = 0x7" enables deauth wake up (bit 2), unicast wake up (bit 1), magic packet (bit 0)
# - driver Makefile:
# - #bit0: ROAM_ON_EXPIRED, #bit1: ROAM_ON_RESUME, #bit2: ROAM_ACTIVE
# - CONFIG_ROAMING_FLAG = 0x3
2023-09-27 01:04:53 +00:00
{ config , lib , pkgs , . . . }:
let
cfg = config . sane . wowlan ;
patternOpts = with lib ; types . submodule {
options = {
2023-09-28 20:09:04 +00:00
ipv4 . destPort = mkOption {
2023-09-27 01:04:53 +00:00
type = types . nullOr types . port ;
default = null ;
description = ''
IP port from which the packet was * sent * .
use this if you want to wake when an outbound connection shows activity
( e . g . this machine made a long-running HTTP request , and the other side finally has data for us ) .
'' ;
} ;
2023-09-28 20:09:04 +00:00
ipv4 . srcPort = mkOption {
2023-09-27 01:04:53 +00:00
type = types . nullOr types . port ;
default = null ;
description = ''
IP port on which the packet was * received * .
use this if you want to wake on inbound connections
( e . g . sshing * into * this machine ) .
'' ;
} ;
2023-09-28 20:55:18 +00:00
arp . queryIp = mkOption {
type = types . nullOr ( types . listOf types . int ) ;
default = null ;
description = ''
IP address being queried .
e . g . ` [ 192 168 0 100 ] `
'' ;
} ;
2023-09-27 01:04:53 +00:00
} ;
} ;
# bytesToStr: [ u8|null ] -> String
# format an array of octets into a pattern recognizable by iwpriv.
# a null byte means "don't care" at its position.
bytesToStr = bytes : lib . concatStringsSep " : " (
builtins . map
( b : if b == null then " - " else hexByte b )
bytes
) ;
# format a byte as hex, with leading zero to force a width of two characters.
# the wlan driver doesn't parse single-character hex bytes.
hexByte = b : if b < 16 then
" 0 " + ( lib . toHexString b )
else
lib . toHexString b ;
2023-09-28 20:55:18 +00:00
etherTypes . ipv4 = [ 08 00 ] ; # 0x0800 = IPv4
etherTypes . arp = [ 08 06 ] ; # 0x0806 = ARP
formatEthernetFrame = ethertype : dataBytes : let
bytes = [
# ethernet frame: <https://en.wikipedia.org/wiki/Ethernet_frame#Structure>
## dest MAC address (this should be the device's MAC, but i think that's implied?)
null null null null null null
## src MAC address
null null null null null null
## ethertype: <https://en.wikipedia.org/wiki/EtherType#Values>
] ++ etherTypes . " ${ ethertype } "
++ dataBytes ;
in bytesToStr bytes ;
formatArpPattern = pat :
formatEthernetFrame " a r p " ( [
# ARP frame: <https://en.wikipedia.org/wiki/Address_Resolution_Protocol#Packet_structure>
## hardware type
null null
## protocol type. same coding as EtherType
08 00 # 0x0800 = IPv4
## hardware address length (i.e. MAC)
06
## protocol address length (i.e. IP address)
04
## operation
00 01 # 0x0001 = request
## sender hardware address
null null null null null null
## sender protocol address
null null null null
## target hardware address
## this is left as "Don't Care" because the packets we want to match
## are those mapping protocol addr -> hw addr.
## sometimes clients do include this field if they've seen the address before though
null null null null null null
## target protocol address
] ++ pat . queryIp ) ;
2023-09-28 20:09:04 +00:00
# formatIpv4Pattern: patternOpts.ipv4 -> String
2023-09-27 01:04:53 +00:00
# produces a string like this (example matches source port=0x0a1b):
# "-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:0a:1b:-:-"
2023-09-28 20:09:04 +00:00
formatIpv4Pattern = pat : let
2023-09-27 01:04:53 +00:00
destPortBytes = if pat . destPort != null then {
high = pat . destPort / 256 ;
low = lib . mod pat . destPort 256 ;
} else {
high = null ; low = null ;
} ;
srcPortBytes = if pat . srcPort != null then {
high = pat . srcPort / 256 ;
low = lib . mod pat . srcPort 256 ;
} else {
high = null ; low = null ;
} ;
2023-09-28 20:55:18 +00:00
in
formatEthernetFrame " i p v 4 " [
2023-09-27 01:04:53 +00:00
# IP frame: <https://en.wikipedia.org/wiki/Internet_Protocol_version_4#Header>
## Version, Internet Header Length. 0x45 = 69 decimal
2023-09-27 01:26:51 +00:00
null # should be 69 (0x45), but fails to wake if i include this
2023-09-27 01:04:53 +00:00
## Differentiated Services Code Point (DSCP), Explicit Congestion Notification (ECN)
null
## total length
null null
## identification
null null
## flags, fragment offset
null null
## Time-to-live
null
## protocol: <https://en.wikipedia.org/wiki/List_of_IP_protocol_numbers>
6 # 6 = TCP
## header checksum
null null
## source IP addr
null null null null
## dest IP addr
null null null null
# TCP frame: <https://en.wikipedia.org/wiki/Transmission_Control_Protocol#TCP_segment_structure>
srcPortBytes . high srcPortBytes . low
destPortBytes . high destPortBytes . low
## rest is Don't Care
] ;
in
{
options = with lib ; {
sane . wowlan . enable = mkOption {
default = false ;
type = types . bool ;
} ;
sane . wowlan . patterns = mkOption {
default = [ ] ;
type = types . listOf patternOpts ;
description = ''
each entry represents a pattern which if seen in a packet should wake the system .
if any pattern matches , the system will wake .
for a pattern to match , all of its non-null fields must match .
'' ;
} ;
} ;
config = lib . mkIf cfg . enable {
systemd . services . wowlan = {
description = " c o n f i g u r e t h e W i F i c h i p t o w a k e t h e s y s t e m o n s p e c i f i c a c t i v i t y " ;
path = [ pkgs . iw pkgs . wirelesstools ] ;
script = let
2023-09-28 20:55:18 +00:00
extractPatterns = pat : lib . flatten [
( lib . optional ( pat . ipv4 != { destPort = null ; srcPort = null ; } ) ( formatIpv4Pattern pat . ipv4 ) )
( lib . optional ( pat . arp != { queryIp = null ; } ) ( formatArpPattern pat . arp ) )
] ;
allPatterns = lib . flatten ( builtins . map extractPatterns cfg . patterns ) ;
encodePattern = pat : ''
iwpriv wlan0 wow_set_pattern pattern = $ { pat }
2023-09-27 01:04:53 +00:00
'' ;
2023-09-28 20:55:18 +00:00
encodedPatterns = lib . concatStringsSep
2023-09-27 01:04:53 +00:00
" \n "
2023-09-28 20:55:18 +00:00
( builtins . map encodePattern allPatterns ) ;
2023-09-27 01:04:53 +00:00
in ''
set - x
iw phy0 wowlan enable any
iwpriv wlan0 wow_set_pattern clean
2023-09-28 20:55:18 +00:00
$ { encodedPatterns }
2023-09-27 01:04:53 +00:00
'' ;
serviceConfig = {
# TODO: re-run this periodically, just to be sure?
# it's kinda bad if this fails or gets undone unexpectedly.
Type = " o n e s h o t " ;
RemainAfterExit = true ;
Restart = " o n - f a i l u r e " ;
RestartSec = " 3 0 s " ;
} ;
after = [ " n e t w o r k - o n l i n e . t a r g e t " ] ;
wantedBy = [ " m u l t i - u s e r . t a r g e t " ] ;
} ;
} ;
}