Update documentation and add status API functions

src/rp2_common/wifi_settings_connect/README.md

@@ -3,12 +3,13 @@
 This is a library to manage WiFi connections. It provides Flash storage
 for WiFi passwords and hotspot names, and a background async\_context
 service to automatically connect to them. You can store details for
-up to 100 hotspots and update them using `picotool` or a setup
-application. This avoids any need to
-specify build-time flags such as `WIFI_SSID` and `WIFI_PASSWORD`.
+up to 100 hotspots and update them using
+[picotool](https://github.com/raspberrypi/pico-sdk-tools/releases).
+or a [setup application](https://github.com/jwhitham/pico-wifi-settings/releases/).
+This avoids any need to specify build-time flags such as `WIFI_SSID` and `WIFI_PASSWORD`.
 
 WiFi hotspot details are stored in a Flash sector that isn't normally used by programs,
-normally located near the end of Flash memory. This 
+normally located near the end of Flash memory. This
 [wifi-settings file](doc/SETTINGS_FILE.md) is a simple text file which
 can be updated by USB or by installing a setup app from the
 [pico-wifi-settings home page](https://github.com/jwhitham/pico-wifi-settings)

src/rp2_common/wifi_settings_connect/doc/INTEGRATION.md

@@ -105,8 +105,15 @@ size of the buffer.
  - `wifi_settings_get_ip_status_text()` produces a line of
    text describing the status of the `lwip` network stack e.g. IP address; this will be empty
    if unconnected.
+ - `wifi_settings_get_ip` produces the IP address by itself; this will be empty
+   if unconnected.
+ - `wifi_settings_get_ssid` produces the current SSID by itself; this will be empty
+   if unconnected. If connected using a BSSID, this will be reported as
+   a `:`-separated lower-case MAC address, e.g. `01:23:45:67:89:ab`. If the wifi-settings
+   file has been updated since the connection was made, then the result may be `?`,
+   as the SSID is found by searching the wifi-settings file.
 
-There is also a function to report the current connection state
+There is also a function to report the current connection state.
 `wifi_settings_get_ssid_status()` returns
 a pointer to a static string, indicating the status of a connection attempt to
 an SSID, e.g. `SUCCESS`, `NOT FOUND`.
@@ -115,6 +122,6 @@ Your application can call `wifi_settings_disconnect()` to force disconnect,
 or `wifi_settings_deinit()` to deinitialise the driver, but this is never necessary
 and these steps can be left out. They exist to allow the application to shut down WiFi,
 e.g. to save power, or in order to control the WiFi hardware directly for some other
-purpose. For example, the 
+purpose. For example, the
 [setup app](https://github.com/jwhitham/pico-wifi-settings/tree/master/doc/SETUP_APP.md)
 uses this feature to perform its own WiFi scan.

src/rp2_common/wifi_settings_connect/doc/SETTINGS_FILE.md

@@ -6,7 +6,7 @@ is called the "WiFi settings file". It is similar to a file on a disk,
 except that it is always at the same location, and the size is
 limited to 4096 bytes.
 
-The file can be updated over USB by using [picotool](https://github.com/raspberrypi/picotool).
+The file can be updated over USB by using [picotool](https://github.com/raspberrypi/pico-sdk-tools/releases).
 It is a text file which can be edited with any text editor.
 Here is an example of typical contents:
 ```
@@ -46,11 +46,9 @@ You can also use the following:
 
 # Copying the WiFi settings file by USB
 
-You can use [picotool](https://github.com/raspberrypi/picotool) to copy the
-file from your PC to your Pico via USB.
-
-picotool is part of the Pico SDK. 
-You need to build picotool with USB support for your OS (or download a pre-built copy).
+You can use
+[picotool](https://github.com/raspberrypi/pico-sdk-tools/releases).
+to copy the file from your computer to your Pico via USB.
 
 To use picotool,
 boot the Pico in bootloader mode by holding down the BOOTSEL button while plugging it
@@ -60,7 +58,7 @@ The default address is 16kb before the final address in Flash:
  - On Pico W, use `0x101fc000` as the address.
  - On Pico 2 W, use `0x103fc000` as the address.
 
-You must also rename your WiFi settings file so that it ends with `.bin` as 
+You must also rename your WiFi settings file so that it ends with `.bin` as
 picotool is not able to upload files unless they are `.bin`, `.elf` or `.uf2`.
 
 Here is a sample upload command for Pico W (RP2040):
@@ -96,9 +94,13 @@ and Pico 2 W (RP2350):
 ```
     picotool save -r 0x103fc000 0x103fd000 backup.bin
 ```
-Characters after the end of the file will be copied (usually either 0x00 or 0xff).
-These can be safely deleted using your text editor. The backup is restored by
-using `picotool load` as described in "Copying the WiFi settings file by USB".
+Bytes after the end of the file will also be copied (usually either 0x00 or 0xff).
+These can be safely deleted. Some text editors will allow you to delete them,
+but if you have any difficulty, you can also remove them with a shell command such as:
+```
+    LC_ALL=C sed -i 's/[\x00\xFF]//g' backup.bin
+```
+The backup is restored using `picotool load` as described in "Copying the WiFi settings file by USB".
 
 These examples use the default location for the wifi-settings file. If you
 are using a custom location, e.g. building with

src/rp2_common/wifi_settings_connect/include/wifi_settings/wifi_settings_configuration.h

@@ -48,7 +48,7 @@
 // is the recommended value, but any positive multiple of the Flash sector size
 // can be used.
 #ifndef WIFI_SETTINGS_FILE_SIZE
-#define WIFI_SETTINGS_FILE_SIZE         (FLASH_SECTOR_SIZE)   // (0x1000 bytes)
+#define WIFI_SETTINGS_FILE_SIZE         (1 * FLASH_SECTOR_SIZE)   // (0x1000 bytes)
 #endif
 
 // Minimum time between initialisation and the first scan (milliseconds).

src/rp2_common/wifi_settings_connect/include/wifi_settings/wifi_settings_connect.h

@@ -62,6 +62,18 @@ int wifi_settings_get_hw_status_text(char* text, int text_size);
 /// @return Return code from snprintf when formatting
 int wifi_settings_get_ip_status_text(char* text, int text_size);
 
+/// @brief Get the IP address by itself
+/// @param[inout] text Text buffer for address
+/// @param[in] text_size Available space in the buffer (bytes)
+/// @return Return code from snprintf when formatting
+int wifi_settings_get_ip(char* text, int text_size);
+
+/// @brief Get the current SSID by itself
+/// @param[inout] text Text buffer for SSID
+/// @param[in] text_size Available space in the buffer (bytes)
+/// @return Return code from snprintf when formatting
+int wifi_settings_get_ssid(char* text, int text_size);
+
 /// @brief Get the status of a connection attempt to
 /// an SSID as a static string, e.g. SUCCESS, NOT_FOUND. "" is returned
 /// if the SSID index is not known.

src/rp2_common/wifi_settings_connect/include/wifi_settings/wifi_settings_flash_storage.h

@@ -22,6 +22,8 @@
 /// @param[out] value Value for key (if found) - not '\0' terminated
 /// @param[inout] value_size Size of the value
 /// @return true if key found
+/// @details This function has a weak symbol, allowing it to be reimplemented
+/// by applications in order to load settings from some other storage
 bool wifi_settings_get_value_for_key(
             const char* key,
             char* value, uint* value_size);

src/rp2_common/wifi_settings_connect/wifi_settings_connect.c

@@ -127,6 +127,37 @@ int wifi_settings_get_ip_status_text(char* text, int text_size) {
         ip4addr_ntoa_r(netif_ip4_gw(g_wifi_state.netif), addr_buf3, IPV4_ADDRESS_SIZE));
 }
 
+int wifi_settings_get_ip(char* text, int text_size) {
+    if ((!g_wifi_state.netif)
+    || (!netif_is_link_up(g_wifi_state.netif))) {
+        // Not connected - return empty string
+        text[0] = '\0';
+        return 0;
+    }
+    char addr_buf[IPV4_ADDRESS_SIZE];
+    return snprintf(text, text_size,
+        "%s",
+        ip4addr_ntoa_r(netif_ip4_addr(g_wifi_state.netif), addr_buf, IPV4_ADDRESS_SIZE));
+}
+
+int wifi_settings_get_ssid(char* text, int text_size) {
+    char ssid[WIFI_SSID_SIZE];
+    uint8_t bssid[WIFI_BSSID_SIZE];
+
+    switch(g_wifi_state.cstate) {
+        case CONNECTING:
+        case CONNECTED_IP:
+            (void) fetch_ssid(g_wifi_state.selected_ssid_index, ssid, bssid);
+            // The text buffer will contain '?' if the SSID is unknown (e.g. if
+            // the wifi-settings file was updated to remove the SSID while connected).
+            return snprintf(text, text_size, "%s", ssid);
+        default:
+            // Not connected - return empty string
+            text[0] = '\0';
+            return 0;
+    }
+}
+
 const char* wifi_settings_get_ssid_status(int ssid_index) {
     if ((ssid_index >= 1) && (ssid_index <= MAX_NUM_SSIDS)) {
         switch (g_wifi_state.ssid_scan_info[ssid_index]) {

src/rp2_common/wifi_settings_connect/wifi_settings_flash_storage.c

@@ -11,10 +11,14 @@
 #include "wifi_settings/wifi_settings_flash_storage.h"
 #include "wifi_settings/wifi_settings_flash_range.h"
 
+#include "pico/platform.h"
+
 #include <string.h>
 
 
-bool wifi_settings_get_value_for_key(
+// Scan the settings file in Flash for a particular key.
+// This function can be reimplemented in order to load settings from some other storage
+__weak bool wifi_settings_get_value_for_key(
             const char* key, char* value, uint* value_size) {
 
     wifi_settings_flash_range_t fr;