Initial commit

basic-udp/readme.md

@@ -0,0 +1,128 @@
+# Raspberry Pi Pico W – Minimal Wi-Fi UDP Example (Arch Linux)
+
+## Authorship
+
+This document was generated using ChatGPT (OpenAI), version 5.2.
+It has not been independently reviewed or validated yet.
+
+## Purpose
+
+Minimal Pico W Wi-Fi example using the Arch Linux packaged Pico SDK.
+Goal: clean build, no hidden assumptions, raw lwIP usage.
+
+---
+
+## Environment
+
+* Arch Linux
+* `pico-sdk` from `/usr/share/pico-sdk`
+* Board: Pico W
+* Toolchain: `arm-none-eabi-gcc`
+* lwIP in `NO_SYS` mode
+* Driver: `pico_cyw43_arch_lwip_poll`
+
+---
+
+Add the following sections.
+
+---
+
+## Build
+
+```sh
+mkdir build
+cd build
+cmake ..
+make -j
+```
+
+Explanation:
+
+* `cmake ..` configures the project and generates build files.
+* `make -j` builds using all available CPU cores.
+* After configuration, normal source changes require only `make -j`.
+* If `CMakeLists.txt` changes, delete the `build/` directory and run `cmake` again.
+
+The resulting firmware file:
+
+```
+build/pico_w_udp_client.uf2
+```
+
+---
+
+## Flash
+
+```sh
+picotool load -f pico_w_udp_client.uf2
+```
+
+This writes the UF2 image to the Pico W over USB (device must be in BOOTSEL mode or rebooted via picotool).
+
+---
+
+## Runtime Behavior
+
+After flashing and reset:
+
+1. The Pico W connects to the configured Wi-Fi network.
+2. Once DHCP assigns an IP address, the onboard LED turns on.
+3. The device begins sending periodic `hello world` UDP messages to the configured destination IP address.
+
+
+## CMake Configuration
+
+Board is selected in `CMakeLists.txt`:
+
+```cmake
+set(PICO_BOARD pico_w)
+include(pico_sdk_import.cmake)
+```
+
+Wi-Fi credentials are kept outside the main source tree:
+
+```cmake
+target_include_directories(pico_w_udp_client PRIVATE
+	${CMAKE_CURRENT_LIST_DIR}
+	${CMAKE_CURRENT_LIST_DIR}/../secrets
+)
+```
+
+Example usage:
+
+```c
+#include "secrets/fra.h"
+```
+
+This keeps credentials separate from firmware logic.
+
+---
+
+## Networking Model
+
+* lwIP raw API (UDP)
+* `NO_SYS = 1`
+* Explicit polling via `cyw43_arch_poll()`
+* Project-local `lwipopts.h`
+
+No sockets, no netconn, no `sys_arch`, no background threads.
+
+---
+
+## Key Points
+
+* Arch SDK requires providing your own `lwipopts.h`.
+* Sockets require `NO_SYS = 0` and a `sys_arch` implementation — not used here.
+* Raw API is the simplest and fully self-contained option.
+* TCP/UDP framing must be handled at application level.
+
+---
+
+## Result
+
+✔ Builds cleanly
+✔ Pico W connects to Wi-Fi
+✔ UDP packets transmitted
+✔ Deterministic configuration
+
+