Add support for esp32 network driver scanning for access points

[UncleGrumpy]

Add network:wifi_scan/0,1 to esp32 network driver, giving the ability for devices configured for "station mode" (or with "station + access point mode") to scan for available access points.

note: these changes depend on PR #1181

Closes #2024

These changes are made under both the "Apache 2.0" and the "GNU Lesser General
Public License 2.1 or later" license terms (dual license).

SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later

[petermm]

I struggled here:

I started out empty example and tried:

    scan = :network.wifi_scan()
    IO.inspect(scan)

This crashes with: {noproc,{gen_server,call,[network,get_config]}} - looks like there is a code path for handling the error but it's never reached

Then I read docs, about having to start the network, and tried:

 config = [
      {:sta,
       [
         {:ssid, "Wokwi-GUEST"},
         {:psk, ""},
         {:connected,
          fn ->
            IO.inspect("network CONNECTED")
            :ok
          end}
       ]}
    ]

    case :network.start(config) do
      {:ok, _pid} ->
        IO.inspect("network started")
      error ->
        :io.put_chars("\nAn error occurred starting network:")
        :erlang.display(error)
    end

    scan = :network.wifi_scan()
    IO.inspect(scan)

which crashed with: wifi:sta_scan: STA is connecting, scan are not allowed!

delaying things and scanning after connection is done made it further to a crash:

CRASH 
======
pid: <0.1.0>

Stacktrace:
undefined

cp: #CP<module: 11, label: 31, offset: 26>

x[0]: error
x[1]: badarg
x[2]: error

Stack 
------

#CP<module: 11, label: 32, offset: 26>
<<"0">>
#CP<module: 11, label: 24, offset: 20>
#CP<module: 10, label: 11, offset: 11>
{0,[{none,[{rssi,undefined},{authmode,undefined},{channel,undefined}]}]}

It also seems that connecting to a network not available, disallows scanning with: wifi:sta_scan: STA is connecting, scan are not allowed!

Would be great seeing an example that could be used in CI eg:

1. scan with no network configured
2. connect known good network - scan
3. config known unavailable network - scan
4. probably some ap stuff
   etc.

I'll work on getting wokwi CI going so this can be covered by CI.

[UncleGrumpy]

I did not add an example yet, my plan was to write a demonstration of “roaming” for atomvm_examples. It is a little difficult to use until #1181 is merged, that will allow starting WiFi without immediately starting a connection. Scans will always fail when a connection is in progress, so your application will need to start a scan after obtaining an IP address, or before any connection is started (which is not possible until after #1181).

[UncleGrumpy]

I wish your second example had a stacktrace! You can see the scan result did come back with no networks found… this can happen with default scans (the dwell time is very short by default - and can easily miss networks, in my experience). I think it’s just a bad match in your test that is crashing there.

[petermm]

I wish your second example had a stacktrace! You can see the scan result did come back with no networks found… this can happen with default scans (the dwell time is very short by default - and can easily miss networks, in my experience). I think it’s just a bad match in your test that is crashing there.

ohh the embarrassment lol - it's the IO.inspect call that crashes, will look into it - used to throwing anything at IO.inspect..

Makes sense with the other stuff, suppose some kind of WifiManager GenServer will materialize, while this PR is on driver primitives level..

I'll test #1181 and help land that first..

[UncleGrumpy]

My plan precisely! The PRs I have already submitted will provide all the necessary low level functionality, but I would like to create a higher level network_manager module that can simplify configuration and orchestration.

[UncleGrumpy]

As far as “dwell” time for the scan, I have found between 300-500ms will find all of the available networks, with the default (120ms) I do notice networks being frequently missed.

[UncleGrumpy]

it's the IO.inspect call that crashes, will look into it - used to throwing anything at IO.inspect..

That does sound like a bug, from my limmited understanding of Elixir you should be able to give it just about anything, much like erlang:display/1.

[UncleGrumpy]

{0,[{none,[{rssi,undefined},{authmode,undefined},{channel,undefined}]}]}

You did point me to a problem here, I started testing more boards and realized that even with maximum dwell time no network are being found. I cherry-picked these commits from a different local branch and must have missed something.

[UncleGrumpy]

When I split up the working branch I was testing new network features on I mistakenly submitted this PR first, but in order to use the scan function PR #1181 needs to be merged first, and this will need to be rebased.

[UncleGrumpy]

{0,[{none,[{rssi,undefined},{authmode,undefined},{channel,undefined}]}]}

I did find a bug that would cause the results to be empty if only a single network was found, during most of my testing I had multiple networks, so this didn't get caught. @petermm, thanks for testing and helping me correct this!

[UncleGrumpy]

closed by accident.

[petermm]

Looking good! - did a full sim test, and we fail on all esp32s2, no crash just error - so will investigate that later on real hw - probably just low mem, which code then seemed to handle, eg. it didn't crash (think solution is to lower results or something, from distant memory)

let's add a check and network:stop() to simtest test_wifi_scan.erl

-module(test_wifi_scan).

-export([start/0]).

start() ->
    {ok, _Pid} = network:start([{sta, [managed]}]),
    {ok, {Num, Networks}} = network:wifi_scan(),
    io:format("network:wifi_scan found ~p networks.~n", [Num]),
    lists:foreach(
        fun(
            _Network =
                #{
                    ssid := SSID,
                    rssi := DBm,
                    authmode := Mode,
                    bssid := BSSID,
                    channel := Number
                }
        ) ->
            io:format(
                "Network: ~p, BSSID: ~p, signal ~p dBm, Security: ~p, channel "
                "~p~n",
                [SSID, binary:encode_hex(BSSID), DBm, Mode, Number]
            )
        end,
        Networks
    ),
    true = lists:any(fun(#{ssid := SSID}) -> SSID =:= <<"Wokwi-GUEST">> end, Networks),
    ok = network:stop(),
    ok.

LLM review: feel free to pick and choose! think most importantly is the ssid data type charlist vs binary?

PR #1165 Review — Add network:wifi_scan/0,1 to ESP32 network driver

Branch: pr/1165
Commits reviewed: feef99b08 (Add network:wifi_scan/0,1) and 44e29c15a (Document new wifi functions)

---

Must Fix

1. SSIDs should be returned as binaries, not charlists (network_driver.c)

Severity: critical
SSIDs are currently built with term_from_string which creates Erlang charlists. This causes two problems:

• Elixir compatibility: Elixir uses binaries as default strings. Consuming SSIDs as charlists from Elixir is awkward (~c"MyNetwork" instead of "MyNetwork"). BSSIDs are already returned as binaries, so this is inconsistent.
• Heap sizing bug: The per-AP heap estimate uses SSID_MAX_SIZE (33) which is the raw byte count. Charlists require TERM_STRING_SIZE(32) (~64 terms) — roughly double. This under-allocation can cause stack-heap overwrite / memory corruption with longer SSIDs.
• Memory efficiency: Binaries use significantly less heap than charlists (header + word-aligned data vs 2 terms per byte), which matters on memory-constrained chips like esp32s2.

Note: the test file test_wifi_scan.erl already assumes SSIDs are binaries (SSID =:= <<"Wokwi-GUEST">>) — this match will fail against the current charlist return.

Fix: Change term_from_string to term_from_literal_binary for SSIDs in wifi_ap_records_to_list_maybe_gc, and update the heap sizing to use TERM_BINARY_HEAP_SIZE(SSID_MAX_SIZE - 1):

// SSIDs — change from charlist to binary:
ssid = term_from_literal_binary(ap_records[i].ssid, ssid_size, heap, global);

// Heap sizing — update ap_data_size:
size_t ap_data_size = TUPLE_SIZE(2) + term_map_size_in_terms(5)
    + TERM_BINARY_HEAP_SIZE(SSID_MAX_SIZE - 1) + TERM_BINARY_HEAP_SIZE(BSSID_SIZE);

If charlists are preferred for backward compatibility, the heap sizing must still be fixed:

size_t ap_data_size = TUPLE_SIZE(2) + term_map_size_in_terms(5)
    + TERM_STRING_SIZE(SSID_MAX_SIZE - 1) + TERM_BINARY_HEAP_SIZE(BSSID_SIZE);

2. Double-wrapping {error, …} in wifi_scan (network_driver.c)

Severity: high
Several call sites in wifi_scan create an error tuple with port_create_error_tuple(ctx, BADARG_ATOM) and then pass the result to send_scan_error_reply, which internally calls port_create_error_tuple again. This produces {error, {error, badarg}} instead of the intended {error, badarg}.

Affected lines (in wifi_scan):

term error = port_create_error_tuple(ctx, BADARG_ATOM);
send_scan_error_reply(ctx, pid, ref, error);  // double-wraps!

Fix: Pass the bare reason atom directly:

send_scan_error_reply(ctx, pid, ref, BADARG_ATOM);

3. Use-after-free if esp_event_handler_unregister fails (network_driver.c)

Severity: high
In send_scan_results, if esp_event_handler_unregister fails, data (ScanClientData) is still freed. The still-registered handler can then fire again and access freed memory. This affects multiple paths:

• Success path at end of send_scan_results
• calloc failure for ap_records (line ~443)
• esp_wifi_scan_get_ap_records failure (line ~465–466)
• esp_wifi_scan_start failure in wifi_scan (line ~1488)

Fix: Only free data when esp_event_handler_unregister succeeds. If it fails, intentionally leak data (the lesser evil) and log the error.

4. Missing defensive clamp on num_results after esp_wifi_scan_get_ap_records (network_driver.c)

Severity: medium
esp_wifi_scan_get_ap_records(&num_results, ap_records) updates num_results by reference. If it were to return a value larger than what was allocated for ap_records, subsequent iteration in wifi_ap_records_to_list_maybe_gc would read out of bounds.

Fix: Save the allocated count before the call and clamp afterward:

uint16_t max_results = num_results;
esp_err_t err = esp_wifi_scan_get_ap_records(&num_results, ap_records);
if (num_results > max_results) {
    num_results = max_results;
}

---

Should Fix

5. Scan result misattribution race (network.erl / network_driver.c)

Severity: medium
All scan requests share the same port Ref. If a scan is cancelled and a new one is started, late results from the old scan arrive with the same Ref and can be delivered to the new scan_receiver.

Fix: Generate a per-scan ref in handle_call({scan,...}), send it to the port, and match on it in handle_info to ignore stale results.

6. Inconsistent cancel message atom (network.erl)

Severity: low
On cancellation, Pid receivers get {scan_done, {error, canceled}} but on success they get {scan_results, Results}. The mismatched wrapper atoms (scan_done vs scan_results) make it harder for receivers to handle both cases uniformly.

Fix: Use {scan_results, {error, canceled}} for Pid receivers on cancellation.

---

Low Priority

7. Typo in docs: "per-chanel" (network.erl)

Severity: low
Line 478: per-chanel → per-channel

8. Typo in docs: "an not" (network.erl)

Severity: low
Line 489: an not in the process → and not in the process

---

Positive Notes

• Dynamic gen_server:call timeout calculation based on channel count and dwell time is well designed — prevents timeouts on 5 GHz capable chips.
• Defensive calloc/malloc failure handling throughout the C driver is solid for embedded targets.
• Immediate freeing of scan_config after esp_wifi_scan_start is correct per ESP-IDF semantics.
• Good documentation and examples covering both blocking and callback scan modes.