From b3b05582bb542ba5c22dd577b7213132606d3533 Mon Sep 17 00:00:00 2001 From: Winford Date: Wed, 22 May 2024 12:04:31 -0700 Subject: [PATCH] Document new wifi functions in Network Programmers Guide Adds documentation for `network:wifi_scan/0,1` and updates details for `network:sta_rssi/0`, as well as better organizing the sub sections that these commands are documented in. Signed-off-by: Winford --- doc/src/network-programming-guide.md | 36 +++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/doc/src/network-programming-guide.md b/doc/src/network-programming-guide.md index c46346b46..1ed31be9e 100644 --- a/doc/src/network-programming-guide.md +++ b/doc/src/network-programming-guide.md @@ -100,7 +100,41 @@ case network:wait_for_sta(Config, 15000) of end ``` -To obtain the signal strength (in decibels) of the connection to the associated access point use [`network:sta_rssi/0`](./apidocs/erlang/eavmlib/network.md#sta_rssi0). +### STA (or AP+STA) mode functions + +Some functions are only available if the device is configured in STA or AP+STA mode. + +#### `sta_rssi` + +Once connected to an access point, the signal strength in decibel-milliwatts (dBm) of the connection to the associated access point may be obtained using [`network:sta_rssi/0`](./apidocs/erlang/eavmlib/network.md#sta_rssi0). The value returned as `{ok, Value}` will typically be a negative number, but in the presence of a powerful signal this can be a positive number. A level of 0 dBm corresponds to the power of 1 milliwatt. A 10 dBm decrease in level is equivalent to a ten-fold decrease in signal power. + +#### `wifi_scan` + +```{notice} +This function is currently only supported on the ESP32 platform. +``` + +After the network has been configured for STA mode and started, you may scan for available access points at any time with [`network:wifi_scan/0`](./apidocs/erlang/eavmlib/network.md#wifi_scan1) or [`network:wifi_scan/1`](./apidocs/erlang/eavmlib/network.md#wifi_scan1). Scanning for access points will temporarily inhibit other network traffic, but will not cause an active connection to be dropped. With no options, a default 'active' scan, with a per-channel dwell time of 120ms will be used and will return network details for up to 6 access points. The return value for the scan takes the form of a tuple consisting of `{ok, Results}`, where `Results = {FoundAPs [NetworkList]}`. `FoundAPs` may be a number larger than the length of the NetworkList if more access points were discoverd than the number of results requested. The entries in the `NetworkList` take the form of `{SSID, [AP_Properties]}`. `SSID` is the name of the network, and the `AP_Properties` is a proplist with the keys `rssi` for the dBm signal strength of the access point, `authmode` value is the authentication method used by the network, and the `channel` key for obtaining the primary channel for the network. + +Example return results: +```erlang +{ok,{13,[{"atomvm_test_ap",[{rssi,-25},{authmode,wpa_wpa2_psk},{channel,6}]}, + {"HotSpot",[{rssi,-47},{authmode,wpa2_wpa3_psk},{channel,6}]}, + {"phishin hole",[{rssi,-50},{authmode,open},{channel,1}]}, + {"The Neighbors Car",[{rssi,-58},{authmode,wpa3_enterprise_192},{channel,4}]}, + {"nothing to see here",[{rssi,-64},{authmode,wpa3_ext_psk_mixed},{channel,11}]}, + {"Public Access",[{rssi,-75},{authmode,open},{channel,1}]}]}} +``` + +The default scan is quite fast, and likely may not find all the available networks. Scans are quite configurable with `active` (the default) and `passive` modes. Options should take the form of a proplist. The per channel scan time can be changed with the `dwell` key, the channel dwell time can be set for up to 1500 ms. Passive scans are slower, as they always linger on each channel for the full dwell time. Passive mode can be used by simply adding `passive` to the configuration proplist. Keep in mind when choosing a dwell time that between each progressively scanned channel the device must return to the home channel for a short time (typically 30ms), but for scans with a dwell time of over 1000ms the home channel dwell time will increase to 60ms to help mitigate beacon timeout events. In some network configuration beacon timeout events may still occur, but should not lead to a dropped connection, and after the scan completes the device should receive the next beacon from the access point. The default of 6 access points in the returned `NetworkList` may be changed with the `results` key. By default hidden networks are ignored, but can be included in the results by adding `show_hidden` to the configuration. + +For example to do a passive scan, including hidden networks, using the longest allowed scan time and showing the maximum number of networks available use the following: + +```erlang + {ok, Results} = network:wifi_scan([passive, {results, 20}, {dwell, 1500}, hidden]), +``` + +For convenience the default options used for `network:wifi_scan/0` may be configured along with the `sta_config()` used to start the network driver. For the corresponding configuration keys consult the [`network:sta_scan_config()`](./apidocs/erlang/eavmlib/network.md) type definition. ## AP mode