Demonstrate using the status led API

Author: peterharperuk

CMakeLists.txt

@@ -85,6 +85,7 @@ add_subdirectory(pio)
 add_subdirectory(pwm)
 add_subdirectory(reset)
 add_subdirectory(rtc)
+add_subdirectory(status_led)
 add_subdirectory(spi)
 add_subdirectory(system)
 add_subdirectory(timer)

README.md

@@ -371,6 +371,13 @@ App|Description
 [max7219_8x7seg_spi](spi/max7219_8x7seg_spi) | Attaching a Max7219 driving an 8 digit 7 segment display via SPI.
 [max7219_32x8_spi](spi/max7219_32x8_spi) | Attaching a Max7219 driving an 32x8 LED display via SPI.
 
+### Status Led
+
+App|Description
+---|---
+[status_blink](status_led) | Blink the onboard LED using the status LED API.
+[color_blink](status_led) | Blink the onboard colored (WS2812) LED using the status LED API if supported by the board.
+
 ### System
 
 App|Description

status_led/# Overview.md

@@ -0,0 +1,104 @@
+# Overview
+
+This example demonstrates how to implement an Over The Air (OTA) software update mechanism using facilities provided by the RP2350 bootrom.
+
+A python script runs on a host machine to _push_ a new (UF2 format) software image to a Pico 2 W running the `ota_update` example image. The incoming image is received via the LwIP IP stack and programmed into Pico 2 W flash memory.
+
+On successful completion of the flash programming, the Pico 2 W will be rebooted and the updated operating image will be selected and executed by the RP2350 bootrom.  This process can be repeated as required.
+
+## More detail
+
+The Pico 2 W listens on TCP port 4242.  The host [python_ota_update.py](python_ota_update.py) script transmits the update image in a series of fixed sized chunks.  Each chunk contains an integer number of UF2 image blocks.  If the update image UF2 block count is not an exact sub-multiple of the number of chunks the script will pad the last chunk as required.
+
+On receipt of pushed chunks, the ota_update image will program the UF2 block stream into flash using the APIs provided by the RP2350 bootrom. In addition to programming, each chunk is 'hashed', using SHA256, and the calculated hash transmitted to the host as an acknowledgement of the received chunk. The host script compares the local and remotely computed hashes and if data corruption has occurred the update will halt.
+
+The flash must be appropriately  partitioned for this example to work. Two ` IMAGE_DEF` partitions are required, one for the currently running software and the other which is updated by the `ota_update` example.
+
+Note: This example _also_ demonstrates how the CYW43 Wi-fi firmware can be stored in a separate flash partition(s). This means the Pico 2 W application can be updated separately which reduces the size of the update download.
+
+For more information flash partitioning and boot image selection please see section 5 of [RP2350 datasheet](https://datasheets.raspberrypi.com/rp2350/rp2350-datasheet.pdf)
+
+## How to run the example
+
+### Flash partitioning
+
+Before the example can be run, the Flash on the Pico 2 W must be appropriately partitioned.
+
+Flash partitioning only needs to be done once for this example but, as written below, will completely remove any previous flash contents.
+
+The required partition data can be loaded by creating a UF2 from the partition table JSON in this folder:
+
+```
+picotool partition create main.json pt.uf2
+```
+then dragging & dropping this UF2 onto the device, or loading it using `picotool` and rebooting:
+```
+picotool load pt.uf2
+picotool reboot -u
+```
+
+> **NOTE**
+> `reboot -u` reboots back to bootsel mode so we can send more commands to the device
+
+Once the partition table is loaded, you then need to load the Wi-Fi firmware UF2 (`picow_ota_update_wifi_firmware.uf2`) followed by loading and executing the main program (`picow_ota_update.uf2`) - either by dragging and dropping them in order, or using `picotool`:
+```
+picotool load picow_ota_update_wifi_firmware.uf2
+picotool load -x picow_ota_update.uf2
+```
+
+> **NOTE**
+> `load -x` attempts to execute the uf2 after the load
+
+The device should now have the following firmware layout. You can confirm this by running "`picotool info`
+
+| Partition | Purpose |
+| ----------|-------- |
+| 0         | Partition A for the application firmware |
+| 1         | Partition B for the application firmware |
+| 2         | Partition A for the wifi firmware |
+| 3         | Partition B for the wifi firmware |
+
+### Operation
+
+This example will send debug output text on the default UART. On startup it displays the current boot partition (from where the firmware is running) and IP address of the Pico 2 W
+
+```
+Boot partition was 0
+Starting server at 192.168.0.103 on port 4242
+```
+
+Once running, you can use [python_ota_update.py](python_ota_update.py) to upload new UF2s from the host to the Pico 2 W using its IP address.  For example:
+```
+python ./python_ota_update.py 192.168.0.103 picow_ota_update.uf2
+```
+This will update the Pico 2 W at `192.168.0.103` with the specified image.
+
+```
+Boot partition was 1
+...
+Starting server at 192.168.0.103 on port 4242
+```
+
+The update is downloaded into the free boot partition that's not currently in use, before rebooting the Pico 2 W to take the new software into use. After the restart the boot partition should have changed.
+
+### Try before you Buy
+
+The `picow_ota_update.uf2` application is marked with the "Try Before You Buy" (TBYB) attribute by specifying `PICO_CRT0_IMAGE_TYPE_TBYB=1` in its compile definitions.
+
+This means that if a newly downloaded image partition is not explicitly "bought" by calling the `rom_explicit_buy` function within 16.7 seconds, the device will reboot and revert to the previously used partition. This gives some protection against a bad OTA update being applied. See section 5.1.17 of [RP2350 datasheet](https://datasheets.raspberrypi.com/rp2350/rp2350-datasheet.pdf) for more details about Try Before You Buy.
+
+#### Wifi Firmware
+
+This example also demonstrates how TBYB can be applied to other partitions - in this case the Wifi firmware. In debug builds you should see debug output which shows the partition that's currently being used for the wifi firmware.
+
+The example uses the `pico_use_wifi_firmware_partition` keyword to make the Wifi firmware appear in its own partition rather than embedded in the application as is usually the case.
+
+```
+Chosen CYW43 firmware in partition 2
+```
+
+Two UF2 files are generated for the wifi firmware, `picow_ota_update_wifi_firmware.uf2` and `picow_ota_update_wifi_firmware_tbyb.uf2`. These images are the same except only the latter image has the TBYB attribute set.
+
+You can update the current Wifi partition with these UF2 files using [python_ota_update.py](python_ota_update.py).
+
+If you use `picow_ota_update_wifi_firmware_tbyb.uf2` for the update then if something goes wrong before the partition is explicitly "bought" by calling the `rom_explicit_buy` function, then the device will switch back to the previous working Wifi firmware partition after a reboot. This does not happen if you use `picow_ota_update_wifi_firmware.uf2` for the update. In this way the TBYB attribute gives you some protection against an OTA update applying bad Wifi firmware.

status_led/CMakeLists.txt

@@ -0,0 +1,29 @@
+# Blink the "status" LED connected to the GPIO defined by PICO_DEFAULT_LED_PIN for your board
+add_executable(status_blink
+    status_blink.c
+)
+# You can define PICO_DEFAULT_LED_PIN yourself to add a led to a different GPIO
+#target_compile_definitions(status_blink PRIVATE
+#   PICO_DEFAULT_LED_PIN=15
+#)
+target_link_libraries(status_blink
+    pico_stdlib
+    pico_status_led
+)
+pico_add_extra_outputs(status_blink)
+example_auto_set_url(status_blink)
+
+# Blink the colored "status" LED connected to the GPIO defined by PICO_DEFAULT_WS2812_PIN for your board
+add_executable(color_blink
+    color_blink.c
+)
+# You can define PICO_DEFAULT_WS2812_PIN yourself to add a WS2812 led to a normal GPIO
+target_compile_definitions(color_blink PRIVATE
+   PICO_DEFAULT_WS2812_PIN=16
+)
+target_link_libraries(color_blink
+    pico_stdlib
+    pico_status_led
+)
+pico_add_extra_outputs(color_blink)
+example_auto_set_url(color_blink)

status_led/color_blink.c

@@ -0,0 +1,35 @@
+/**
+ * Copyright (c) 2025 Raspberry Pi (Trading) Ltd.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "pico/stdlib.h"
+#include "pico/status_led.h"
+
+#if !PICO_COLORED_STATUS_LED_AVAILABLE
+#warning The color_blink example requires a board with a WS2812 LED
+#endif
+
+#ifndef LED_DELAY_MS
+#define LED_DELAY_MS 250
+#endif
+
+int main() {
+    bool rc = status_led_init();
+    hard_assert(rc);
+    hard_assert(colored_status_led_supported()); // This assert fails if your board does not have WS2812 support
+    uint32_t count = 0;
+    while (true) {
+        // flash red then green then blue
+        uint32_t color = PICO_COLORED_STATUS_LED_COLOR_FROM_RGB(count % 3 == 0 ? 0xaa : 0, count % 3 == 1 ? 0xaa : 0, count % 3 == 2 ? 0xaa : 0); 
+        colored_status_led_set_on_with_color(color);
+        count++;
+        sleep_ms(LED_DELAY_MS);
+        assert(colored_status_led_get_state());
+        colored_status_led_set_state(false);
+        sleep_ms(LED_DELAY_MS);
+        assert(!colored_status_led_get_state());
+    }
+    status_led_deinit();
+}

status_led/status_blink.c

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2025 Raspberry Pi (Trading) Ltd.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "pico/stdlib.h"
+#include "pico/status_led.h"
+
+#ifndef LED_DELAY_MS
+#define LED_DELAY_MS 250
+#endif
+
+int main() {
+    bool rc = status_led_init();
+    hard_assert(rc);
+    while (true) {
+        status_led_set_state(true);
+        sleep_ms(LED_DELAY_MS);
+        assert(status_led_get_state());
+        status_led_set_state(false);
+        sleep_ms(LED_DELAY_MS);
+        assert(!status_led_get_state());
+    }
+    status_led_deinit();
+}