Updated "Network Programmers Guide" documentation

Adds descriptions of new configuration options and `connect/0,1`,
`disconnect/0`, and `sta_status/0` functions.

Signed-off-by: Winford <winford@object.stream>

Author: UncleGrumpy

doc/src/network-programming-guide.md

@@ -27,14 +27,16 @@ The `<sta-properties>` property list should contain the following entries:
 * `{ssid, string() | binary()}`  The SSID to which the device should connect.
 * `{psk, string() | binary()}` The password required to authenticate to the network, if required.
 
+Optionally on the ESP32 platform, using the `managed` atom in the configuration, the `ssid` and `psk` may be omitted, but if they are also supplied a connection will not be initiated immediately. The initially configured connection can be started using [`network:connect/0`](./apidocs/erlang/eavmlib/network.md#connect0). This will allow for the use of `network:wifi_scan` to find available access points, and connecting with [`network:connect/1`](./apidocs/erlang/eavmlib/network.md#connect1) to update the `ssid` and `psk` for a new connection. When starting the driver in this mode all callback functions must be configured when the driver is started, and providing a callback for `disconnected` events is recommended, so the application can also control when, and to which access point, it will make a new connection.
+
 The [`network:start/1`](./apidocs/erlang/eavmlib/network.md#start1) will immediately return `{ok, Pid}`, where `Pid` is the process ID of the network server instance, if the network was properly initialized, or `{error, Reason}`, if there was an error in configuration.  However, the application may want to wait for the device to connect to the target network and obtain an IP address, for example, before starting clients or services that require network access.
 
 Applications can specify callback functions, which get triggered as events emerge from the network layer, including connection to and disconnection from the target network, as well as IP address acquisition.
 
 Callback functions can be specified by the following configuration parameters:
 
 * `{connected, fun(() -> term())}` A callback function which will be called when the device connects to the target network.
-* `{disconnected, fun(() -> term())}` A callback function which will be called when the device disconnects from the target network.
+* `{disconnected, fun(() -> term())}` A callback function which will be called when the device disconnects from the target network. If no callback function is provided the default behavior is to attempt to reconnect immediately. By providing a callback function the application can decide whether to reconnect, or connect to a new access point.
 * `{got_ip, fun((ip_info()) -> term())}` A callback function which will be called when the device obtains an IP address.  In this case, the IPv4 IP address, net mask, and gateway are provided as a parameter to the callback function.
 
 ```{warning}
@@ -75,7 +77,8 @@ gotIp(IpInfo) ->
     io:format("Got IP: ~p~n", [IpInfo]).
 
 disconnected() ->
-    io:format("Disconnected from AP.~n").
+    io:format("Disconnected from AP, attempting to reconnect~n"),
+    network:connect().
 ```
 
 In a typical application, the network should be configured and an IP address should be acquired first, before starting clients or services that have a dependency on the network.
@@ -102,6 +105,35 @@ 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
+
+#### `sta_status`
+
+The function [`network:sta_status/0`](./apidocs/erlang/eavmlib/network.md#sta_status0) may be used
+any time after the driver has been started to get the current connection state of the sta
+interface. When a connection is initiated, either at start up or when `network:connect/1` is used
+in application `managed` mode (which will start with a `disconnected` state) the interface will be
+marked as `connecting` followed by `associated` after a connection is established with an access
+point. After receiving an IP address the connection will be fully `connected`. If a beacon timeout
+event is received (this indicates poor signal strength or a heavily congested network) the status
+will change to `degraded` for the remainder of the connection session. This does not always mean
+that the connection is still poor, but it can be a helpful diagnostic when experiencing network
+problems, and often does result in a dropped connection. When stopping the interface with
+`network:disconnect/0` the state will change to `disconnecting` until the interface is completely
+stopped and set to `disconnected`.
+
+#### `disconnect`
+
+The function [`network:disconnect/0`](./apidocs/erlang/eavmlib/network.md#disconnect0) will disconnect a station from the associated access point. Note that using this function without providing a custom `disconnected` event callback function will result in the driver immediately attempting to reconnect to the last associated access point.
+
+This function is currently only supported on the ESP32 platform.
+
+#### `connect`
+
+Using the function [`network:connect/0`](./apidocs/erlang/eavmlib/network.md#connect0) will start a connection to the last configured access point. To connect to a new access point use either a proplist consisting of `[{ssid, "Network Name"} | {psk, "Password"} | {dhcp_hostname, "hostname"}]`, or a complete `network_config()` consisting of `[sta_config() | sntp_config()]`.  If any callback functions or default scan configuration options are defined in the `network_config()` they will be ignored; default scan options and callback functions must be configured when the driver is started.
+
+This function is currently only supported on the ESP32 platform.
+
 ## AP mode
 
 In AP mode, the ESP32 starts a WiFi network to which other devices (laptops, mobile devices, other ESP32 devices, etc) can connect.  The ESP32 will create an IPv4 network, and will assign itself the address `192.168.4.1`.  Devices that attach to the ESP32 in AP mode will be assigned sequential addresses in the `192.168.4.0/24` range, e.g., `192.168.4.2`, `192.168.4.3`, etc.