diff --git a/pico_w/wifi/mqtt/README b/pico_w/wifi/mqtt/README.md
similarity index 87%
rename from pico_w/wifi/mqtt/README
rename to pico_w/wifi/mqtt/README.md
index e1889bb61..e3bc2ab9b 100644
--- a/pico_w/wifi/mqtt/README
+++ b/pico_w/wifi/mqtt/README.md
@@ -34,8 +34,8 @@ When building the code set the host name of the MQTT server, e.g.
 export MQTT_SERVER=myhost
 cmake ..
 ```
-
-The example should publish its core temperature to the /temperature topic. You can subscribe to this topic from another machine.
+The example checks its core temperature every ten seconds and if it has changed, publishes it to the
+/temperature topic. You can subscribe to this topic from another machine.
 
 ```
 mosquitto_sub -h $MQTT_SERVER -t '/temperature'
@@ -47,6 +47,11 @@ You can turn the led on and off by publishing messages.
 mosquitto_pub -h $MQTT_SERVER -t '/led' -m on
 mosquitto_pub -h $MQTT_SERVER -t '/led' -m off
 ```
+You can check the current the state of the led by subscribing to the /led/state topic on another machine.
+```
+mosquitto_sub -h $MQTT_SERVER -t '/led_state'
+```
+
 
 # Security
 
diff --git a/pico_w/wifi/mqtt/mqtt_client.c b/pico_w/wifi/mqtt/mqtt_client.c
index b70d6885d..8b454eaef 100644
--- a/pico_w/wifi/mqtt/mqtt_client.c
+++ b/pico_w/wifi/mqtt/mqtt_client.c
@@ -243,6 +243,8 @@ static void mqtt_connection_cb(mqtt_client_t *client, void *arg, mqtt_connection
         if (!state->connect_done) {
             panic("Failed to connect to mqtt server");
         }
+        // note that the main() loop will soon terminate because mqtt_client_is_connected()
+        // will return false.  
     }
     else {
         panic("Unexpected status");
@@ -368,7 +370,13 @@ int main(void) {
         panic("dns request failed");
     }
 
+    // We are not in a callback but we can get away with calling mqtt_client_is_connected()
+    // because it's a read-only operation
     while (!state.connect_done || mqtt_client_is_connected(state.mqtt_client_inst)) {
+        // As supplied the example configures cyw43_arch for thread_safe_background operation
+        // by linking `pico_cyw43_arch_lwip_threadsafe_background` in CMakeLists.txt, so the 
+        // following two lines are unnecessary (but do no harm). However you will need them 
+        // if you reconfigure the build to use cyw43_arch in polling mode.
         cyw43_arch_poll();
         cyw43_arch_wait_for_work_until(make_timeout_time_ms(10000));
     }