RaftNetworkManagerSysMod

NetworkManager SysMod

Overview

The Network Manager module is responsible for managing the network state, including WiFi and Ethernet configuration, retries, and connection monitoring. It provides APIs to configure WiFi in both STA (Station) and AP (Access Point) modes, manage Ethernet settings, and monitor network status.

NetworkManager Settings

When constructed normally (in RaftCoreApp for instance) the NetworkManager is configured using the contents of the SysTypes key NetMan. The settings available to configure Network are described in Network Manager Settings

---

Constructor

NetworkManager::NetworkManager

• Parameters:
  • pModuleName: The name of the network module.
  • sysConfig: The system configuration object.

Initializes the Network Manager with the given module name and system configuration. It also sets the module as a singleton instance.

---

Setup

NetworkManager::setup

Sets up the network based on the provided configuration, including enabling WiFi STA and AP modes, setting SSID and password, and configuring the hostname.

• Steps:
  • Retrieves the network settings from the system configuration.
  • Sets the hostname based on the system's friendly name (if available).
  • Configures the network (WiFi STA/AP modes and Ethernet).
  • Logs the network configuration.
  • Configures WiFi STA and AP SSID and passwords.

---

Loop

NetworkManager::loop

The loop function is called frequently to service the network system and monitor changes in connection status. It triggers registered callbacks on status changes.

• Functionality:
  • Services the network system.
  • Checks for changes in connection status (whether an IP address is assigned).
  • Notifies registered callbacks if the status changes.

---

API Endpoints

The NetworkManager exposes several REST API endpoints to control network settings. These include configuring WiFi, scanning for networks, and managing WiFi credentials.

API List

The API for NetworkManager is included in the Raft API List

Endpoint	Method	Description
/w	GET	Setup WiFi in STA mode, e.g., /w/SSID/password.
/wap	GET	Setup WiFi in AP mode, e.g., /wap/SSID/password.
/wc	GET	Clear WiFi settings.
/wifipause	GET	Pause or resume WiFi, e.g., /wifipause/pause, /wifipause/resume.
/wifiscan	GET	Scan for WiFi networks: /wifiscan/start starts a scan, /wifiscan/results returns scan status (in progress / done / failed) and cached results.

API Details

/w (WiFi STA Setup)

• Description: Configures the WiFi STA mode by setting the SSID and password.
• Method: GET
• URL Parameters:
  • SSID: The WiFi SSID.
  • Password: The WiFi password.
• Example: /w/SSID/password
• Response: JSON with success or failure of configuration.

/wap (WiFi AP Setup)

• Description: Configures the WiFi AP mode by setting the SSID and password.
• Method: GET
• URL Parameters:
  • SSID: The WiFi AP SSID.
  • Password: The WiFi AP password.
• Example: /wap/SSID/password
• Response: JSON with success or failure of configuration.

/wc (WiFi Clear)

• Description: Clears the stored WiFi credentials and optionally restarts the system.
• Method: GET
• URL Parameters: Optionally, norestart to avoid restarting the system.
• Example: /wc/norestart
• Response: JSON with success or failure of the WiFi clear operation.

/wifipause (WiFi Pause/Resume)

• Description: Pauses or resumes WiFi operations.
• Method: GET
• URL Parameters:
  • pause to pause WiFi.
  • resume to resume WiFi.
  • any other value (e.g. status) reports whether WiFi is paused without changing it.
• Example: /wifipause/pause
• Response: JSON with the WiFi pause status, e.g. {"req":"wifipause/status","isPaused":1,"rslt":"ok"}.

/wifiscan (WiFi Scan)

• Description: Scans for available WiFi access points. The scan runs asynchronously: start kicks it off and returns immediately, and results is polled to find out when it has finished and to get the list of access points.
• Method: GET
• URL Parameters:
  • start to start scanning. Returns the scan status.
  • results to get the scan status and the cached results of the last completed scan.
• Example: /wifiscan/start
• Response: JSON with a scan status object and (for results) a wifi list of access points.

The behaviour described here applies to RaftCore versions after 1.54.1. Earlier firmware behaves differently - see Older firmware below. Clients that need to work with both should follow Client polling guidance.

wifiscan/start

Starts a new scan and returns the scan status:

{"req":"wifiscan/start","scan":{"state":"scanning","id":1,"elapsedMs":0},"rslt":"ok"}

• A start request while a scan is already in progress is not an error - the scan is not restarted and the status of the running scan is returned (id is unchanged).
• A start request within 1 second of a scan completing does not start a new scan either - the status of the just-completed scan is returned (state is done, id is unchanged and ageMs is small) and its results are fresh. This protects against repeated start requests which were queued while the link was unresponsive during the scan (see Client polling guidance).
• rslt is fail only if the scan could not be started. The scan object is still returned, with state of failed and the reason in err:

{"req":"wifiscan/start","scan":{"state":"failed","id":2,"durMs":0,"ageMs":0,"err":"busy (STA connecting)","count":7,"found":7,"new":0,"lost":0},"rslt":"fail"}

The most common reason is busy (STA connecting): the ESP-IDF WiFi driver rejects a scan while a station connection attempt is in progress (which happens repeatedly if the configured SSID is not reachable). The client can simply retry the start a short time later.

wifiscan/results

Returns the scan status and the cached results of the last completed scan. rslt is always ok - the scan.state value indicates whether a scan is in progress, done or failed.

While a scan is in progress (the wifi list holds the results of the previous completed scan, or is empty if there hasn't been one):

{"req":"wifiscan/results","scan":{"state":"scanning","id":1,"elapsedMs":850},"wifi":[],"rslt":"ok"}

When the scan is complete:

{
  "req":"wifiscan/results",
  "scan":{"state":"done","id":1,"durMs":2410,"ageMs":120,"count":2,"found":2,"new":0,"lost":0},
  "wifi":[
    {"ssid":"rd01","rssi":-66,"ch1":6,"ch2":0,"auth":"WPA2_PSK","bssid":"aa:aa:9a:17:89:bb","pair":"CCMP","group":"CCMP","new":0},
    {"ssid":"rd01","rssi":-81,"ch1":11,"ch2":0,"auth":"WPA2_PSK","bssid":"aa:aa:9a:17:92:c4","pair":"CCMP","group":"CCMP","new":0}
  ],
  "rslt":"ok"
}

Results are cached by the firmware as soon as the scan completes, so results can be requested any number of times (and at any later time - use ageMs to judge how fresh they are). A scan typically takes a few seconds as all channels are scanned.

scan status object

Field	Present	Description
state	always	idle (no scan has been started since boot), scanning (scan in progress - any results are from the previous scan), done (scan completed - results are current) or failed (scan could not start or did not complete - see err; any results are from the last completed scan)
id	always	Scan counter, incremented each time a new scan is started (0 before the first scan). A client can use the id returned by start to confirm that a done state refers to the scan it started
elapsedMs	scanning	Time since the scan started
durMs	done, failed	How long the scan took
ageMs	done, failed	Time since the scan ended
err	failed	Reason for failure: busy (STA connecting) or an ESP-IDF error name (e.g. ESP_ERR_WIFI_NOT_STARTED) if the scan could not be started, aborted if the driver reported that the scan did not complete, abandoned if WiFi was paused (see wifipause) during the scan
count	once a scan has completed	Number of access points in the wifi list (a maximum of 30 are retained)
found	once a scan has completed	Number of access points found by the WiFi driver (may exceed count)
new	once a scan has completed	Number of access points (BSSIDs) in the results that were not present in the previous completed scan (0 for the first scan)
lost	once a scan has completed	Number of access points (BSSIDs) in the previous completed scan which are no longer present (0 for the first scan)

Note that count, found, new and lost always describe the last completed scan so, while state is scanning or failed, they (like the wifi list) refer to an earlier scan.

wifi list entries

Field	Description
ssid	Network name. A network with several access points (e.g. a mesh network) appears once per access point with the same ssid and different bssid values
rssi	Signal strength in dBm. Entries are in the order provided by the ESP-IDF WiFi driver - strongest signal first
ch1	Primary channel
ch2	Secondary channel (0 = none, otherwise the ESP-IDF wifi_second_chan_t value)
auth	Authentication mode, e.g. OPEN, WPA2_PSK, WPA2_WPA3_PSK
bssid	Access point MAC address
pair	Pairwise cipher, e.g. CCMP
group	Group cipher, e.g. CCMP
new	1 if this BSSID was not present in the previous completed scan, otherwise 0 (always 0 for the first scan)

Older firmware (RaftCore 1.54.1 and earlier)

Earlier firmware supports the same two operations but with a simpler response:

• There is no scan object in any response and no new field in the wifi entries.
• wifiscan/start returns {"req":"wifiscan/start","rslt":"ok"} (or "rslt":"fail" if the scan could not be started, with no reason given).
• wifiscan/results returns {"req":"wifiscan/results","rslt":"fail"} while the scan is in progress - this does not indicate an error, just that the results are not ready yet.
• When the scan is complete wifiscan/results returns {"req":"wifiscan/results","wifi":[...],"rslt":"ok"}.
• Results are not cached - they are read directly from the WiFi driver, which frees its list when it is read. results should therefore only be requested once after a scan completes - further requests return empty or invalid data.

Client polling guidance

Two practical points apply to any client:

• The link may be unresponsive during the scan. If the client is connected over WiFi (HTTP or WebSocket) the device generally cannot send or receive while its radio is scanning, so responses (including the response to wifiscan/start) may be delayed until the scan ends several seconds later and no scanning status will be seen. A client should therefore allow a long response timeout and should not automatically re-send wifiscan/start when a response is slow. Repeated start requests queued during the scan are all delivered at the moment it completes: current firmware ignores a start within 1 second of a scan completing, but firmware without this protection (including older firmware) starts another scan. Over BLE or serial the link remains responsive and the scanning state can be observed.
• A scan cannot be started while WiFi is paused (see wifipause - some systems pause WiFi while a BLE client is connected). wifiscan/start fails with an ESP-IDF error such as ESP_ERR_WIFI_NOT_INIT. Check with wifipause/status, resume WiFi for the scan and pause it again afterwards (the raftjs wifiScan() option resumeWifiIfPaused does this).

A client can support both current and older firmware using the presence of the scan object to distinguish them (the raftjs RaftSystemUtils.wifiScan() method implements this procedure, with an optional progress callback):

1. Send wifiscan/start. If the response has "rslt":"fail" the scan did not start - scan.err (if present) gives the reason and, for busy (STA connecting), it is reasonable to retry after a second or so. If present, note the scan.id value.
2. Poll wifiscan/results at a modest rate (e.g. every 500-1000 ms) with an overall timeout (e.g. 15 s).
3. For each results response:
   • scan object present (current firmware): if scan.state is scanning keep polling (the wifi list, if not empty, is from the previous scan and can be shown as interim information); if done (and scan.id matches the value from step 1) the wifi list is the result of the scan; if failed stop (or restart the scan) and report scan.err.
   • no scan object (older firmware): "rslt":"fail" means the scan is still in progress so keep polling; "rslt":"ok" with a wifi list means the scan is complete - keep this list and don't request results again as the next request will return an empty list.

---

JSON Status and Debug

NetworkManager::getStatusJSON

Returns the current network status in JSON format, including the system version and connection status.

• Example:

  {
    "rslt": "ok",
    "v": "1.0.0",
    "hostname": "mydevice"
  }