Skip to content

NetworkModule

Top-level network identity module. Holds the device name and MAC address, manages WiFi mode, and runs the network management policy. Introduced in Sprint 8; management policy added Sprint 10.

What it does

NetworkModule is the parent of all network child modules (WifiStaModule, WifiApModule, EthernetModule). On setup() it:

  • Reads the hardware MAC address and derives a default device name MM-XXXX (last 4 hex digits).
  • Calls WiFi.mode(WIFI_STA) to start in station-only mode. The AP netif is not allocated until WifiApModule actually starts the AP, which avoids a heap fragmentation event when STA connects.
  • Exposes device_name as an editable text control and mac_address as a read-only display.

Child modules call deviceName() to inherit the device name as their AP SSID, so changing device_name once propagates to all children.

On PC, the MAC address is 00:00:00:00:00:00 and device_name defaults to MM-0000.

Management policy

loop() runs a management tick every 10 seconds that enables and disables the AP and STA based on Ethernet and WiFi connectivity:

  • Ethernet connected: disable AP and STA.
  • STA connected (no Ethernet): disable AP.
  • STA just dropped: start a 30-second grace period before re-enabling the AP.
  • Ethernet just dropped: re-enable STA.

For full details including the state diagram, timers, and wiring example, see Developer Guide: Network.

Controls

Key Type Default Description
device_name text MM-XXXX (auto from MAC) Human-readable device name; editable, persisted
mac_address display hardware MAC Read-only; set once in setup()

Parent-child lifecycle

NetworkModule is a parent module. Its children (WifiStaModule, WifiApModule, EthernetModule) are added under it in state/modulemanager.json via "parent_id". The ModuleManager sets up children after the parent.

WifiApModule reads deviceName() via setInput("network", networkModule). NetworkModule receives pointers to all three child modules via setInput("sta"/"ap"/"eth") so the management tick can gate them.

Platform notes

ESP32: reads the eFuse MAC via esp_efuse_mac_get_default(). WiFi starts in WIFI_STA mode; wifi_ap_start() switches to WIFI_AP_STA only when the AP actually starts.

PC: no-op; MAC is zeroed and device name defaults to MM-0000. The management tick is compiled out.

Test coverage

→ Network and WiFi — default device_name format, setProps override, loadState/saveState round-trip, schema includes both controls, category is "network", healthReport contains device= and mac=.

Source