RaftNetworkManagerSettings

NetworkManager Settings

Setting	Description	Type	Default	Example
ethEn	Enables Ethernet. EthEnabled is also accepted.	boolean	false	true
wifiSTAEn	Enables WiFi in STA (Station) mode. WiFiEnabled is also accepted.	boolean	false	true
wifiAPEn	Enables WiFi in AP (Access Point) mode.	boolean	false	true
defaultHostname	Read into the settings but not currently used: the hostname is set from the friendly name.	string	""	"myDevice"
wifiSTAScanThreshold	The WiFi STA scan threshold based on authentication mode - see WiFi Authentication Modes.	string	"WPA2_PSK"	"OPEN"
wifiSTAConnectBySignal	WiFi STA access point selection. When true all channels are scanned and the strongest access point with the configured SSID is joined. When false ESP-IDF's fast scan is used, which joins the first matching access point found (possibly a weak one on a network with multiple access points) but connects a little faster. (RaftCore versions after 1.54.1)	boolean	true	false
startMode	When WiFi is started. auto: at setup. onDemand: not at setup - started and stopped with the NetMan wifiStart / wifiStop commands or the wifistart / wifistop API. See WiFi started on demand below. (RaftCore versions after 1.64.0, RaftSysMods after 1.29.0)	string	"auto"	"onDemand"
wifiSSID, wifiPW	WiFi STA credentials applied by NetMan each time WiFi starts, but only if they differ from the credentials already stored by the WiFi driver (RaftCore versions after 1.64.0, RaftSysMods after 1.29.0 - earlier versions reconfigured them, with a disconnect and reconnect, at every setup). WiFiSSID / WiFiPass are also accepted. wifiAPSSID / wifiAPPW (or WiFiAPSSID / WiFiAPPass) do the same for the AP.	string	""	"myssid"
wifiSTAFastReconnect	Remember the access point connected to (BSSID and channel) and connect straight to it on the next WiFi start without scanning. See Fast reconnect below. (RaftCore versions after 1.64.0)	boolean	false	true
wifiSTAFastReconnectMinRSSI	An access point weaker than this (dBm) isn't remembered, so a better one is looked for on the next start. 0 for no minimum.	int	-80	-75
wifiSTAFastReconnectMaxUses	Scan again after the remembered access point has been used this many times (e.g. to find a better access point on a mesh network). 0 for no limit.	uint32_t	0	20
wifiBand	WiFi band on chips with 5 GHz (ESP-IDF 5.4 or later): 2g or 5g. A scan of one band is much shorter. Any other value (including the default auto) leaves the driver's band setting alone. Set when the station starts, only if different. (RaftCore versions after 1.64.0)	string	"auto"	"2g"
wifiStaticIP	WiFi STA static IP address. Blank for DHCP. When set DHCP is stopped, which saves the time it takes on each connection. Usually set per device with the wifiip API instead. See Static IP below. (RaftCore versions after 1.64.0)	string	""	"192.168.1.30"
wifiStaticGateway	Gateway for the static IP (required with wifiStaticIP).	string	""	"192.168.1.1"
wifiStaticNetmask	Netmask for the static IP.	string	"255.255.255.0"	"255.255.0.0"
wifiStaticDNS	DNS server for the static IP. Blank uses the gateway.	string	""	"8.8.8.8"
wifiTxPowerDbm	Maximum WiFi transmit power in dBm (2 to 20). 0 leaves the ESP-IDF default (20 dBm). Applied before the first connection. Some boards need this limited: see WiFi transmit power below. (RaftCore versions after 1.58.1)	int	0	15
wifiDiag	WiFi link diagnostics, recovery and link options, as an object. See WiFi diagnostics and recovery below. (RaftCore versions after 1.58.1)	object	see below	{"logS": 60}
wifiAPAuthMode	The WiFi AP authentication mode - see WiFi Authentication Modes.	string	"WPA2_PSK"	"WPA3_PSK"
wifiAPMaxConn	The maximum number of connections allowed on the WiFi AP.	uint32_t	4	10
wifiAPChannel	The WiFi AP channel number.	uint32_t	1	6
ethLanChip	The type of Ethernet chip used - see Ethernet LAN Chip Types.	string	"" (none)	"LAN87XX"
ethPowerPin	GPIO pin used to control power for the Ethernet chip (-1 if not used).	int	-1	5
ethMDCPin	GPIO pin used for SMI MDC (Management Data Clock) in Ethernet (-1 if not used).	int	-1	23
ethMDIOPin	GPIO pin used for SMI MDIO (Management Data Input/Output) in Ethernet (-1 if not used).	int	-1	18
ethPhyAddr	The address of the Ethernet PHY (-1 for the driver's auto-detection).	int	-1	1
ethPhyRstPin	GPIO pin used to reset the Ethernet PHY (-1 if not used).	int	-1	16
ethRmiiClockMode	RMII clock of the internal EMAC (ESP-IDF 5.3 or later): INPUT (or EXT_IN) for an external clock in on GPIO0; anything else is a clock out on ethRmiiClockGpio.	string	"OUTPUT"	"INPUT"
ethRmiiClockGpio	GPIO for the RMII clock.	int	17	16
spiHostDevice	SPI host for a W5500 (2 is SPI2_HOST).	int	2	3
spiMOSIPin, spiMISOPin, spiSCLKPin, spiCSPin	SPI pins for a W5500.	int	-1	11
spiIntPin	W5500 interrupt pin. -1 if not wired: the driver then polls the W5500 every 10 ms.	int	-1	4
spiClockSpeedMHz	SPI clock for a W5500 in MHz.	int	20	40
NTPServer	The NTP server used for time synchronization.	string	"pool.ntp.org"	"time.google.com"
timezone	The timezone used for the system clock (set as TZ, so a POSIX TZ string).	string	"UTC"	"GMT0BST,M3.5.0/1,M10.5.0"
enableMDNS	Enables or disables mDNS (Multicast DNS) functionality.	boolean	true	false

WiFi Authentication Modes (wifiSTAScanThreshold, wifiAPAuthMode)

Values are not case sensitive. Any other value is WPA2_PSK.

Auth Mode	Description
OPEN	No authentication (open network).
WEP	Wired Equivalent Privacy (WEP) encryption.
WPA_PSK	WPA Pre-Shared Key (WPA-Personal).
WPA2_PSK	WPA2 Pre-Shared Key (WPA2-Personal).
WPA_WPA2_PSK	WPA/WPA2 mixed mode.
WPA3_PSK	WPA3 Pre-Shared Key (WPA3-Personal).
WPA2_WPA3_PSK	WPA2/WPA3 mixed mode.
WAPI_PSK	WAPI (WLAN Authentication and Privacy Infrastructure).
WPA2_ENTERPRISE	WPA2 Enterprise (using EAP).

Ethernet LAN Chip Types (ethLanChip)

Values are not case sensitive.

Chip Type	Description
"" (or any other value)	No Ethernet chip is used.
LAN87XX	LAN87XX Ethernet PHY on the internal EMAC (RMII).
W5500	WIZnet W5500 SPI Ethernet chip (spi... settings). The firmware must be built with HW_ETH_USE_W5500 defined (and SPI Ethernet enabled in sdkconfig).

WiFi started on demand (startMode)

With "startMode": "onDemand" NetMan sets up the network but doesn't start WiFi - e.g. for a battery device which uses the network on only some of its wakes from deep sleep. (RaftCore versions after 1.64.0, RaftSysMods after 1.29.0)

• Start and stop WiFi from another SysMod with sysModSendCmdJSON("NetMan", R"({"cmd":"wifiStart","fullScan":0})") and {"cmd":"wifiStop"}, or with the wifistart / wifistop API. fullScan 1 forgets the fast reconnect access point for this start.
• wifiSSID / wifiPW are applied when WiFi starts (if they differ from the stored credentials).
• The w, wap and wc APIs start WiFi first if it is stopped.
• While WiFi is stopped, pause and resume (wifipause) and auto-reconnect don't start it, and SysManager's rebootIfDiscMins doesn't count the time as disconnected. With startMode auto (or Ethernet enabled) it counts as before.
• TX power (wifiTxPowerDbm) and the wifiDiag link options are applied each time WiFi starts.

wifiSTAEn (or wifiAPEn) must still be set: wifiStart fails if neither is enabled.

Fast reconnect (wifiSTAFastReconnect)

With wifiSTAFastReconnect the access point connected to (BSSID and channel) is kept in RTC memory, and the next WiFi start connects straight to it without scanning. RTC memory survives deep sleep and software restarts but not power on. (RaftCore versions after 1.64.0)

• First connect / after power on: there is no remembered access point, so a normal scan is made. The access point connected to is then remembered (unless its RSSI is below wifiSTAFastReconnectMinRSSI).
• Remembered access point fails (or the connection to it is lost): it is forgotten and the same WiFi start falls back to a normal scan. The NetMan named value fastFallbacks counts these.
• Used wifiSTAFastReconnectMaxUses times: a scan is made again.
• New credentials (w/SSID/password): the remembered access point is forgotten.
• Full scan ({"cmd":"wifiStart","fullScan":1} or wifistart?fullScan=1): this start forgets the remembered access point and scans all channels (of the wifiBand band) for the strongest - e.g. after a restart, or when connections keep failing. Leave wifiSTAConnectBySignal at its default (true) with fast reconnect: a scan which joins the first access point found can pick a weak one, which fast reconnect then keeps using.
• The remembered access point is set in the WiFi driver's RAM config, so nothing is written to flash on each start.
• Not for networks which rely on 802.11v/k roaming (BTM/MBO), as the device chooses the access point.

For the shortest connection also select the wifi-fast-connect sdkconfig fragment (shorter DHCP - see SysTypes), set wifiBand on chips with 5 GHz, and use a static IP. On an ESP32-C5 waking from deep sleep this took the time from boot to an IP address from 15.3 s (defaults) to about 0.3 s.

Static IP

wifiStaticIP, wifiStaticGateway, wifiStaticNetmask and wifiStaticDNS give the WiFi station a static address with DHCP stopped. An invalid address is logged and DHCP is used. The address must be outside the router's DHCP pool (or reserved for the device). (RaftCore versions after 1.64.0)

As the address differs per device it is usually set with the wifiip API, which keeps it in NVS (namespace netman) and overrides the SysType settings. (RaftSysMods versions after 1.29.0)

The static IP is applied each time WiFi starts, so a change (or wifiip/clear) is used from the next WiFi start (wifistop then wifistart, or a restart). When a static IP was in use and is now cleared (or can't be applied), DHCP is started again. Code using NetworkSystem directly can change it with NetworkSystem::setWifiStaticIP(ip, gateway, netmask, dns) (an empty ip for DHCP, an empty netmask for 255.255.255.0, an empty dns for the gateway), which is likewise used from the next WiFi start. (RaftCore versions after 1.64.0, RaftSysMods after 1.29.0)

WiFi transmit power

Some boards transmit a poor signal at the ESP-IDF default power (20 dBm). Access points then decode their frames badly. Typical symptoms:

• Failed connections: the connection never completes. Disconnect reasons include 2 (authentication expired), 4 (association expired) and 15 (4-way handshake timeout).
• Associated but no data: the device stays associated and reports a good RSSI, but no data gets through in either direction. Pings to the gateway from the device also fail.
• On the access point: a much lower received signal than at the start of the connection. A low receive rate (e.g. 5.5 Mbps on 2.4 GHz). UniFi reports "AP/Client Signal Balance: Poor".

Example: a UM FeatherS3 couldn't connect to a nearby access point at 20 dBm, but connected first time at 15, 11 and 8 dBm. Other ESP32-S3 devices on the same access point were unaffected. Unexpected Maker also recommend a lower transmit power for some of their boards.

Measured on the FeatherS3, with a 3-minute load test at each setting (download = the device transmits):

Access point	20 dBm	15 dBm	11 dBm	8 dBm
Near (device sees -71 dBm)	no connection	198 kB/s, RTT 6 ms	213 kB/s, 7 ms	193 kB/s, 11 ms
Far (device sees -82 dBm)	76 kB/s, RTT 27 ms	438 kB/s, 8 ms	324 kB/s, 12 ms	310 kB/s, 17 ms

Even on the far access point, where it does connect, 20 dBm gave less than a fifth of the throughput of 15 dBm. The FeatherS3 SysTypes in the RaftROS examples use "wifiTxPowerDbm": 15.

Boards using Espressif modules are generally fine at the default power. In the same test an ESP32-S3 WROOM module (in a SandBot) worked at every power, and 20 dBm gave its best results (229 kB/s, RTT 7 ms; 15 dBm: 236 kB/s, 10 ms; 8 dBm: 203 kB/s, 13 ms). So only limit the power on boards which show the symptoms above.

Choosing a value:

• Use the highest power that is reliable, since a lower power reduces range.
• wifidiag?txPwr=N changes the power at runtime, so values can be tried without rebuilding (see wifidiag).
• The test scripts in RaftCore unit_tests/wifi_link_hw include txpower_matrix.py. It measures connection, ping loss and throughput for each access point and power.
• Then set wifiTxPowerDbm in the SysType's NetMan settings, e.g. "wifiTxPowerDbm": 15.

WiFi diagnostics and recovery (wifiDiag)

The wifiDiag object sets the initial WiFi diagnostics, recovery and link options. All fields are optional, and they can also be changed at runtime with the wifidiag endpoint. A txPwr here overrides wifiTxPowerDbm.

Field	Description	Default
pingMs	Interval of pings from the device to its gateway in ms. These detect a link which has stopped passing data. 0 turns off pinging and recovery.	5000
pingRecover	Recover after this many consecutive failed gateway pings while associated (0 = off). See recovery.	4
logS	Interval of a one-line link summary in the log in seconds (0 = off).	0
ps	WiFi power save mode: none, min or max. Applied after each connection.	none
txPwr	Maximum transmit power in dBm (2 to 20, 0 = default).	0
proto	PHY protocols: bgn, bg (no 802.11n, including AMPDU aggregation) or b.	bgn
bw	Bandwidth: 20 or 40 MHz.	ESP-IDF default

Example:

"NetMan": {
    "wifiSTAEn": 1,
    "wifiTxPowerDbm": 15,
    "wifiDiag": {
        "logS": 60
    }
}

A battery device which starts WiFi on demand and connects quickly on a 5 GHz-capable chip:

"NetMan": {
    "wifiSTAEn": 1,
    "startMode": "onDemand",
    "wifiSTAFastReconnect": 1,
    "wifiBand": "2g"
}