Documentation: document the wifibridge save and clear commands.

Documentation/applications/system/wifibridge/index.rst

@@ -41,6 +41,9 @@ The defaults used when an option is not given on the command line are:
 ``CONFIG_NETUTILS_WIFIBRIDGE_DHCPD``
   Allow the ``-d`` option, which runs the DHCP server on the bridge
   (``CONFIG_NETUTILS_DHCPD``).
+``CONFIG_NETUTILS_WIFIBRIDGE_PERSIST``
+  Allow ``save`` and ``clear``, which keep the configuration across resets
+  (see `Keeping the configuration`_).
 
 Change the default passphrase before deploying a board.
 
@@ -50,9 +53,12 @@ Usage
 .. code-block:: console
 
    wifibridge start [-s <ssid>] [-p <passphrase>] [-c <channel>] [-3]
-                    [-a <ipaddr>] [-d]
+                    [-a <ipaddr>] [-d|-D]
    wifibridge stop
    wifibridge status
+   wifibridge save [-s <ssid>] [-p <passphrase>] [-c <channel>] [-3]
+                   [-a <ipaddr>] [-d|-D]
+   wifibridge clear
 
 ``start``
   Configure the Wi-Fi interface as an access point, create the bridge,
@@ -73,17 +79,58 @@ Usage
   ``-d``
     Run the DHCP server on the bridge.  Leave it out when another DHCP
     server is reachable through the Ethernet port.
+  ``-D``
+    Do not run the DHCP server.  It is the default; with ``save`` it
+    turns off a ``-d`` that was kept before.
 ``stop``
   Stop the DHCP server, remove the ports, delete the bridge and stop the
   access point.
 ``status``
   Show whether the bridge exists, its address, the state of the two
   ports and the SSID of the access point.
+``save``
+  Keep the configuration, see `Keeping the configuration`_.  It takes the
+  same options as ``start``, and does not start anything.
+``clear``
+  Forget the saved configuration.
 
 The Ethernet and Wi-Fi interfaces carry no IP address of their own: only
 the bridge does.  The Ethernet interface needs a MAC address, which a
 board without a factory programmed one has to provide.
 
+Keeping the configuration
+=========================
+
+With ``CONFIG_NETUTILS_WIFIBRIDGE_PERSIST``, ``wifibridge save`` keeps the
+SSID, the passphrase, the channel, the security, the address and the DHCP
+server option, and ``wifibridge start`` uses them instead of the defaults
+of the configuration.  The options of ``start`` still win, for that run
+only.  ``wifibridge clear`` forgets them and the defaults are used again.
+The options of ``save`` are applied over what is already saved, if there is
+something, and over the defaults otherwise.
+
+.. code-block:: console
+
+   nsh> wifibridge save -s MyBridge -p mypassphrase -c 11 -a 10.0.0.7 -d
+   nsh> reboot
+   ...
+   nsh> wifibridge start
+   nsh> wifibridge status
+   br0   present 10.0.0.7
+   eth0  up
+   wlan0 up ssid "MyBridge"
+
+The configuration is one record, with a CRC, at the start of
+``CONFIG_NETUTILS_WIFIBRIDGE_STORAGE``.  That is a file of a file system
+that is mounted at boot (the default is ``/data/wifibridge.conf``), or a block
+device, such as the MTD of a few pages of the flash (it needs ``CONFIG_BCH``
+to be opened by name).  Saving a device erases and writes the flash that
+holds it, so it should be used for this alone.  A record that is missing or
+damaged is ignored.  The passphrase is stored as is.
+
+On the PIC32MZ-W1, ``CONFIG_PIC32MZ_PROGMEM`` with ``CONFIG_MTD_PROGMEM``
+provides such a device in the last pages of the program flash.
+
 Example
 =======
 
@@ -102,7 +149,7 @@ Limitations
 * Only the access point mode is supported.  A station cannot be bridged
   at layer 2 because it cannot send frames with foreign source addresses.
 * ``start`` fails with ``EEXIST`` if the bridge already exists.
-* The SSID and the passphrase are not saved: they come from the
-  command line or from the defaults of the configuration.
+* The saved configuration does not include the names of the interfaces and
+  the netmask, which come from the configuration.
 * The rest of the limits of the bridge apply, see
   :doc:`/os/networking/bridge`.