Add simple async_context example (#721)

* Add simple async_context example

* use status_led library, improve comments

* use more intiuitive syntax for pointer to function

---------

Co-authored-by: Martin Crossley <dev@crossleys.biz>

Author: mjcross

.gitignore

@@ -7,3 +7,9 @@ build-*
 build_*
 .DS_Store
 *.pdf
+pio/squarewave/generated/squarewave_wrap.pio.h
+pio/squarewave/generated/squarewave.hex
+pio/squarewave/generated/squarewave.pio.h
+pio/ws2812/generated/ws2812.pio.h
+pio/ws2812/generated/ws2812.py
+.gitignore

CMakeLists.txt

@@ -64,6 +64,7 @@ endif()
 
 # Hardware-specific examples in subdirectories:
 add_subdirectory(adc)
+add_subdirectory(async_context)
 add_subdirectory(binary_info)
 add_subdirectory(bootloaders)
 add_subdirectory(clocks)

README.md

@@ -44,6 +44,11 @@ App|Description
 [dma_capture](adc/dma_capture) | Use the DMA to capture many samples from the ADC.
 [read_vsys](adc/read_vsys) | Demonstrates how to read VSYS to get the voltage of the power supply.
 
+### async_context
+App|Description
+---|---
+[simple_at_time_worker](async_context/simple_at_time_worker) | Use a worker on a threadsafe background context to blink the on-board LED.
+
 ### Binary Info
 
 App|Description

async_context/CMakeLists.txt

@@ -0,0 +1 @@
+add_subdirectory_exclude_platforms(simple_at_time_worker)

async_context/simple_at_time_worker/CMakeLists.txt

@@ -0,0 +1,16 @@
+add_executable(simple_at_time_worker
+    simple_at_time_worker.c
+    )
+
+# common dependencies
+target_link_libraries(simple_at_time_worker
+    pico_stdlib
+    pico_async_context_threadsafe_background    
+    pico_status_led                             # generic control of status LED on different boards 
+    )
+
+# create map/bin/hex file etc.
+pico_add_extra_outputs(simple_at_time_worker)
+
+# add url via pico_set_program_url
+example_auto_set_url(simple_at_time_worker)

async_context/simple_at_time_worker/README.md

@@ -0,0 +1,10 @@
+# Simple at-time worker
+
+A simple example demonstrating how to add an *at-time* worker to an `async_context`.
+
+The program creates an `async_context_threadsafe_background` and uses an *at-time* worker to flash the LED on a Pico or Pico-W board.
+
+## note
+An `async_context_threadsafe_background` is generally used to ensure that a non-reentrant library such as lwIP can be used successfully in a multi tasking application; so a practical networking application would typically use the `async_context` provided by `cyw43_arch` rather than creating its own.
+
+More details about `async_context` can be found under [High Level APIs](https://www.raspberrypi.com/documentation/pico-sdk/high_level.html#group_pico_async_context) in the SDK documentation.

async_context/simple_at_time_worker/simple_at_time_worker.c

@@ -0,0 +1,73 @@
+/**
+ *  Copyright (c) 2026 mjcross
+ * 
+ *  SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "pico/stdlib.h"
+#include "pico/async_context_threadsafe_background.h"
+#include "pico/status_led.h"
+
+#ifndef LED_DELAY_MS
+#define LED_DELAY_MS 500
+#endif
+
+// define a user data type to be passed to our worker's callback function
+typedef struct {
+    bool led_state;
+} my_data_t;
+
+
+// define a callback function for our worker (MUST be safe to call from an IRQ)
+void worker_cb(async_context_t *p_ctx, async_at_time_worker_t *p_worker) {
+    // unpack our user data instance from `(void *)worker.user_data`
+    my_data_t *p_my_data = p_worker->user_data;
+
+    // update the status LED from our user data and toggle it
+    status_led_set_state(p_my_data->led_state);
+    p_my_data->led_state = !p_my_data->led_state;
+
+    // re-schedule the worker, so as to flash the LED continuously (an at_time worker is 
+    // automatically removed from the context just before it runs)
+    async_context_add_at_time_worker_in_ms(p_ctx, p_worker, LED_DELAY_MS);
+}
+
+// create an instance of our user data type (MUST still exist when the worker runs)
+static my_data_t my_data = {
+    .led_state = true 
+};
+
+// create an asynchronous at-time worker that points to our callback function and user
+// data (MUST still exist when the worker runs)
+static async_at_time_worker_t worker = {
+    .do_work = &worker_cb,
+    .user_data = &my_data
+};
+
+
+int main() {
+    // initialise the status LED
+    hard_assert(
+        status_led_init() == true
+    );
+
+    // create and initialise an asynchronous background context with default settings
+    // note: in a networking application we'd probably reuse the existing cyw43_arch
+    // context directly with `async_context_t ctx = cyw43_arch_async_context()`
+    async_context_threadsafe_background_t background;
+    hard_assert(
+        async_context_threadsafe_background_init_with_defaults(&background) == true
+    );
+
+    // add our at-time worker to the background context, to run after LED_DELAY_MS
+    // note: `background.core` is the async_context_t of our threadsafe background. If
+    // we were using the cyw43 context instead (see above) we'd just put `&ctx` here.
+    hard_assert(
+        async_context_add_at_time_worker_in_ms(&background.core, &worker, LED_DELAY_MS) == true
+    );
+
+    // the LED will flash in the background 
+    while(true) {
+        sleep_ms(5000);
+    }
+}