Skip to content

Commit

Permalink
Document new wifi functions in Network Programmers Guide
Browse files Browse the repository at this point in the history
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 <[email protected]>
  • Loading branch information
UncleGrumpy committed Jun 4, 2024
1 parent fcb16fa commit 58cf1f8
Showing 1 changed file with 35 additions and 1 deletion.
36 changes: 35 additions & 1 deletion doc/src/network-programming-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,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

Expand Down

0 comments on commit 58cf1f8

Please sign in to comment.