FreeRTOS on Raspberry Pi Pico W: Select the lwIP Execution Model Before Calling Its APIs

Adding FreeRTOS tasks around a Pico W networking example does not automatically make every lwIP call task-safe. The selected SDK architecture controls servicing, callback context and which API family the application can use.

Identify that execution model before investigating intermittent network failures. This discussion uses Pico SDK 2.3.1's CYW43 architecture header and FreeRTOS integration source. It describes software contracts, not measured Wi-Fi reliability or throughput.

Resolve the architecture target in the build

The tagged architecture header distinguishes polling, thread-safe background and FreeRTOS behavior. The `pico_cyw43_arch_lwip_sys_freertos` integration uses lwIP OS mode, `NO_SYS=0`, and supports the full API including blocking sockets. Its raw lwIP calls still have locking requirements; application calls outside lwIP callbacks need the documented begin/end bracketing.

Do not infer the model from the presence of FreeRTOS elsewhere in the application. A project can still select a different networking architecture. Inspect the linked target and effective lwIP configuration together.

For a hypothetical telemetry application, decide whether networking code uses sockets or the raw callback-oriented API. That decision affects the execution context and ownership rules at each call site. Mixing snippets from the two models without reviewing those rules creates a concurrency problem that a reconnect loop will not fix.

Keep callbacks and ordinary task work distinct

The header notes that the thread-safe background mode can run lwIP callbacks in a low-priority interrupt context, while the FreeRTOS architecture uses a separate task for driver and stack work. In the FreeRTOS integration, high-level CYW43 calls are permitted from tasks or lwIP callbacks, not arbitrary interrupts.

Consequently, review each callback's actual context before using a blocking kernel operation. A function that was safe when called by an application task may not be safe when reused as a callback under another architecture.

A useful design keeps a callback's responsibilities bounded and transfers application work through an appropriate handoff. The exact handoff must respect both the callback context and buffer lifetime. Copying a pointer into a queue is not by itself proof that the referenced data remains valid when another task consumes it.

Check initialization of the chosen context

The FreeRTOS architecture implementation rejects `NO_SYS=1`. It creates or uses an asynchronous context, applies configurable task stack and priority settings, and initializes the CYW43 driver and lwIP integration. If initialization fails, it performs cleanup and reports an error.

Handle that result before starting application network operations. A task that exists is not proof that all of its networking dependencies initialized successfully. Likewise, changing stack or priority settings should respond to measured evidence rather than serve as a substitute for checking the selected architecture.

If supplying a custom asynchronous context, document who owns its initialization and lifetime. The SDK's default-context cleanup behavior does not imply that it owns every application-provided context.

Review call sites by contract, not by apparent success

Classify each networking call as application-task work, lwIP callback work or interrupt-originated work. For raw API calls, verify the required protection at the boundary. For blocking socket operations, confirm that the calling task may block without preventing another dependency from making progress.

Then test one source of concurrency at a time: simultaneous producers, a delayed consumer, reconnect activity or application shutdown. Keep observed failures separate from untested hypotheses. A short successful transfer does not exercise every callback and teardown path.

The useful outcome is a consistent execution model from CMake selection through initialization to the final API call. Once that model is explicit, networking diagnostics can focus on real protocol and resource failures instead of accidental cross-context access.