Improve comments on UTC->local time

Author: Martin Crossley

README.md

@@ -200,7 +200,7 @@ App|Description
 [picow_blink_fast_clock](pico_w/wifi/blink) | Blinks the on-board LED (which is connected via the WiFi chip) with a faster system clock to show how to reconfigure communication with the WiFi chip at build time under those circumstances.
 [picow_iperf_server](pico_w/wifi/iperf) | Runs an "iperf" server for WiFi speed testing.
 [picow_ntp_client](pico_w/wifi/ntp_client) | Connects to an NTP server to fetch and display the current time.
-[picow_ntp_system_time](pico_w/wifi/ntp_system_time) | Creates a background time of day clock that periodically updates itself from a pool of NTP servers, and uses it to display local time.
+[picow_ntp_system_time](pico_w/wifi/ntp_system_time) | Creates a background time-of-day clock that periodically updates itself from a pool of NTP servers, and uses it to display local time.
 [picow_tcp_client](pico_w/wifi/tcp_client) | A simple TCP client. You can run [python_test_tcp_server.py](pico_w/wifi/python_test_tcp/python_test_tcp_server.py) for it to connect to.
 [picow_tcp_server](pico_w/wifi/tcp_server) | A simple TCP server. You can use [python_test_tcp_client.py](pico_w//wifi/python_test_tcp/python_test_tcp_client.py) to connect to it.
 [picow_tls_client](pico_w/wifi/tls_client) | Demonstrates how to make a HTTPS request using TLS.

pico_w/wifi/ntp_system_time/README.md

@@ -4,11 +4,11 @@ Creates a time of day clock that periodically synchronises itself to Internet ti
 
 The example connects to Wi-Fi and displays the local time in the UK or another timezone that you specify, synchronised once an hour to one of the servers from [pool.ntp.org](https://www.ntppool.org/en/). 
 
-Uses the SNTP application provided by lwIP and the Pico 'always-on timer' _(RTC on Pico/rp2040, powman timer on Pico-2/rp2350)_.
+Uses the SNTP application provided by lwIP and the Pico 'always-on timer' _(RTC on Pico/RP2040, powman timer on Pico-2/RP2350)_.
 
 # Running the example
 
-Provide the SSID and password of your Wi-Fi network by editing `CmakeLists.txt` or on the command line; then build and run the example as usual.
+Provide the SSID and password of your Wi-Fi network by editing `CMakeLists.txt` or on the command line; then build and run the example as usual.
 
 You should see something like this:
 
@@ -67,7 +67,7 @@ If you reconfigure it to use _polling mode_ then your user code should periodica
 
 The SDK provides the high level [pico_aon_timer](https://www.raspberrypi.com/documentation/pico-sdk/high_level.html#group_pico_aon_timer) API to provide the same always-on timer functions on Pico and Pico-2 despite their hardware differences.
 
-On the original Pico (rp2040 device) these functions use the real time clock (RTC) and on the Pico-2 (rp2350 device) the POWMAN timer.
+On the original Pico (RP2040) these functions use the real time clock (RTC) and on the Pico-2 (RP2350) the POWMAN timer.
 
 For further details refer to the [SDK documentation](https://www.raspberrypi.com/documentation/pico-sdk/high_level.html#group_pico_aon_timer).
 

pico_w/wifi/ntp_system_time/ntp_system_time.c

@@ -63,11 +63,6 @@ int get_time_utc(struct timespec *ts_ptr) {
 int main() {
     stdio_init_all();
 
-    // If you (optionally) define a POSIX TZ here then the example will display local time instead of UTC.
-    // For the format see https://ftp.gnu.org/old-gnu/Manuals/glibc-2.2.3/html_node/libc_431.html
-    setenv("TZ", "BST0GMT,M3.5.0/1,M10.5.0/2", 1);  // <-- this is the timezone spec for Europe/London
-    // there is no need to call tzset()
-
     // Initialise the Wi-Fi chip
     if (cyw43_arch_init()) {
         printf("Wi-Fi init failed\n");
@@ -96,19 +91,29 @@ int main() {
     struct timespec ts;
     struct tm tm;
 
+    // OPTIONAL: set the 'TZ' env variable to the local POSIX timezone (in this case Europe/London,
+    // to create your own see https://ftp.gnu.org/old-gnu/Manuals/glibc-2.2.3/html_node/libc_431.html)
+    setenv("TZ", "BST0GMT,M3.5.0/1,M10.5.0/2", 1);
+    // If you set 'TZ' then functions like ctime(), localtime() and their variants will automatically 
+    // give results converted to the local timezone instead of UTC (see below).
+
     while (true) {
 
         if(aon_timer_is_initialised) {
 
             // read the current time as UTC seconds and ms since the epoch
             get_time_utc(&ts);
 
-            // if you simply want to display the local time you could now do so with
-            // puts(ctime(&(ts.tv_sec)));
+            // if you just want a string representation of the current time and you're not interested
+            // in the individual date/time fields, you could simply call ctime(&(ts.tv_sec)) here
+            // (if you have set 'TZ' then the result will be in local time, otherwise UTC)
+
+            // unpack the individual date/time fields (if you have set 'TZ' then the values will be
+            // in local time, otherwise UTC)
+            pico_localtime_r(&(ts.tv_sec), &tm);
 
-            // to unpack the hours/mins/seconds etc for the local time zone (if defined, see above) 
-            pico_localtime_r(&(ts.tv_sec), &tm);    // convert UTC linear time to broken-down local time
-            printf("%s: %s", tm.tm_isdst ? "BST": "GMT", asctime(&tm)); // display as text  
+            // display individual date/time fields in human readable form
+            printf("%s: %s", tm.tm_isdst ? "BST": "GMT", asctime(&tm));
 
         } else {
             puts("system time not yet initialised");