Merge pull request atomvm#499 from fadushin/network_api_fix

Fixed examples and docs to reflect API changes

This PR fixes examples and documentation to reflect changes to the return value
from the `network:start` function.

The release notes have been augmented to note that the change to the network
interface is API-incompatible with previous releases of AtomVM.

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

Author: bettio

CHANGELOG.md

@@ -48,6 +48,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   devices to be attached to the same SPI Bus.
 - Changed the return value from `erlang:system_info(esp32_chip_info)` from a tuple to a map, with
 additional information.
+- Changed the return type of the `network:start` function to return the tuple `{ok, Pid}` on a
+successful call, instead of the bare atom `ok`.  Applications that use `network:start` and
+check the return value will need to be modified.
 
 ## [0.5.1] - Unreleased
 ### Added

doc/src/network-programming-guide.md

@@ -29,7 +29,7 @@ The `<sta-properties>` property list should contain the following entries:
 
 > Note that the station mode SSID and password _may_ be stored in non-volatile storage, in which case these parameters may be skipped.  See the "NVS Credentials" section below, for more information about using non-volatile storage to store credentials that persist across device reboots.
 
-The `network:start/1` will immediately return `ok`, 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.
+The `network:start/1` 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.
 
@@ -60,7 +60,7 @@ The following example illustrates initialization of the WiFi network in STA mode
             {dhcp_hostname, <<"myesp32">>}
         ]}
     ],
-    ok = network:start(Config),
+    {ok, Pid} = network:start(Config),
     ...
 
 The following callback functions will be called when the corresponding events occur during the lifetime of the network connection.
@@ -113,7 +113,7 @@ If the password is omitted, then an _open network_ will be created, and a warnin
 
 > Note that the station mode SSID and password _may_ be stored in non-volatile storage, in which case these parameters may be skipped.  See the "NVS Credentials" section below, for more information about using non-volatile storage to store credentials that persist across device reboots.
 
-The `network:start/1` will immediately return `ok`, 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 to be ready to accept connections from other devices, or to be notified when other devices connect to this AP.
+The `network:start/1` will immediately return `{ok, Pid}`, where `Pid` is the process id of the network server, 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 to be ready to accept connections from other devices, or to be notified when other devices connect to this AP.
 
 Applications can specify callback functions, which get triggered as events emerge from the network layer, including when a station connects or disconnects from the AP, as well as when a station is assigned an IP address.
 
@@ -146,7 +146,7 @@ The following example illustrates initialization of the WiFi network in AP mode.
             {sta_disconnected, fun sta_disconnected/1},
         ]}
     ],
-    ok = network:start(Config),
+    {ok, Pid} = network:start(Config),
     ...
 
 The following callback functions will be called when the corresponding events occur during the lifetime of the network connection.

examples/erlang/esp32/ap_sta_network.erl

@@ -47,7 +47,7 @@ start() ->
         {sntp, [{endpoint, "pool.ntp.org"}]}
     ],
     case network:start(Config) of
-        ok ->
+        {ok, _Pid} ->
             sleep_forever();
         Error ->
             erlang:display(Error)

examples/erlang/esp32/morse_server.erl

@@ -34,7 +34,7 @@ start() ->
         ]}
     ],
     case network:start(Config) of
-        ok ->
+        {ok, _Pid} ->
             wait_for_message();
         Error ->
             erlang:display(Error)

libs/eavmlib/src/network.erl

@@ -154,7 +154,7 @@ wait_for_sta(StaConfig, Timeout) ->
     ],
     Config = [{sta, NewStaConfig}],
     case start(Config) of
-        ok ->
+        {ok, _Pid} ->
             wait_for_ip(Timeout);
         Error ->
             Error
@@ -203,7 +203,7 @@ wait_for_ap(ApConfig, Timeout) ->
     ],
     Config = [{ap, NewApConfig}],
     case start(Config) of
-        ok ->
+        {ok, _Pid} ->
             wait_for_ap_started(Timeout);
         Error ->
             Error
@@ -225,10 +225,10 @@ wait_for_ap(ApConfig, Timeout) ->
 -spec start(Config :: network_config()) -> ok | {error, Reason :: term()}.
 start(Config) ->
     case gen_server:start({local, ?MODULE}, ?MODULE, Config, []) of
-        {ok, Pid} ->
+        {ok, Pid} = R ->
             case gen_server:call(Pid, start) of
                 ok ->
-                    {ok, Pid};
+                    R;
                 Error ->
                     Error
             end;
@@ -239,10 +239,10 @@ start(Config) ->
 -spec start_link(Config :: network_config()) -> ok | {error, Reason :: term()}.
 start_link(Config) ->
     case gen_server:start_link({local, ?MODULE}, ?MODULE, Config, []) of
-        {ok, Pid} ->
+        {ok, Pid} = R ->
             case gen_server:call(Pid, start) of
                 ok ->
-                    {ok, Pid};
+                    R;
                 Error ->
                     Error
             end;