# hello_usb (Pico) — Build & Flash

Quick instructions to compile and flash the `hello_usb` project for Raspberry Pi Pico / RP2-based boards.

## Prerequisites

- GNU Arm Embedded Toolchain (arm-none-eabi)
- CMake (>= 3.13) and Ninja
- Pico SDK (included in this repo as `pico-sdk/`) or installed separately
- `picotool` (optional, for USB flashing) or OpenOCD + SWD adapter (for debugging/flashing)
- On macOS: install tools via Homebrew where available (e.g. `cmake`, `ninja`, `open-ocd`)

Ensure `arm-none-eabi-gcc`, `cmake`, and `ninja` are available in `PATH`:

```bash
which arm-none-eabi-gcc cmake ninja
```

## Build

From the project root (where `CMakeLists.txt` lives):

```bash
# set PICO_SDK_PATH to the bundled SDK in this repo (adjust if using system SDK)
export PICO_SDK_PATH=$(pwd)/pico-sdk

mkdir -p build
cd build
# configure & generate (Ninja)
cmake .. -G Ninja
# build
ninja
```

After a successful build you should find artifacts under `build/` such as `hello_usb.uf2` and `hello_usb.elf`.

## Flashing

Choose one of the methods below.

- UF2 (mass-storage) — easiest for Pico in BOOTSEL mode:

  1. Hold BOOTSEL on the Pico and connect it via USB.
  2. Copy `build/hello_usb.uf2` onto the mounted RPI-RP2 mass storage device.

- picotool (USB) — if `picotool` is installed:

```bash
# Example (adjust path if needed):
picotool load build/hello_usb.uf2 -f -x
```

- OpenOCD + SWD (CMSIS-DAP) — for programmers/debugging:

```bash
# Example template (adjust openocd script paths and target cfg for your board):
openocd -s /path/to/openocd/scripts \
  -f interface/cmsis-dap.cfg \
  -f target/rp2040.cfg \
  -c "adapter speed 5000; program \"$(pwd)/build/hello_usb.elf\" verify reset exit"
```

The VSCode workspace already includes tasks for building and flashing:
- `Compile Project` — runs `ninja -C build`
- `Run Project` — uses `picotool` to load the target (see `.vscode/tasks` / your task runner)

## Troubleshooting

- If CMake cannot find the SDK, ensure `PICO_SDK_PATH` points to the `pico-sdk/` folder.
- Verify the toolchain: `arm-none-eabi-gcc --version`.
- If UF2 flashing doesn't work, try `picotool` or an SWD programmer (OpenOCD + CMSIS-DAP).
- For OpenOCD errors, ensure correct interface/target `.cfg` files and that the adapter is connected.

## Notes

- Modify the `cmake` configuration or `CMakeLists.txt` if you need custom board or build options.
- If using a centralized Pico SDK installation, set `PICO_SDK_PATH` to that location instead of the bundled `pico-sdk/`.

If you want, I can run the build here or add a short `Makefile` or CI job to automate builds.