## SDRangel — Copilot instructions

Goal: help an AI coding agent become productive quickly in the SDRangel repo by summarizing the architecture, developer workflows, project conventions and integration points with concrete file references and examples.

- Big picture
  - SDRangel is a Qt-based (Qt5/Qt6 optional) GUI and server frontend for software-defined radio devices. It processes I/Q samples from various SDR hardware, applies signal processing and demodulation/modulation plugins, and exposes a WebAPI for remote control. The interface with hardware is done via "device" plugins. The modulation/demodulation is done via "channel" plugins. Another kind of plugins provide additional features not necessarily depending on the I/Q stream(s) (e.g., rotator control, map display). SDRangel can run as a desktop GUI application or as a headless server exposing a WebAPI.
  Key top-level directories:
    - `app/`, `appbench/`, `appsrv/` — application entry points
    - `sdrbase/` — core application framework shared by app, appsrv, appbench and plugins
    - `sdrgui/` — shared GUI components used by the main app and plugins
    - `sdrsrv/` — shared server components used by appsrv and plugins
    - `settings/` — application settings management
    - `plugins/` — channel, device and feature plugins (primary extension mechanism)
    - `plugins/channelmimo/` — MIMO channel plugins for channels processing multiple synchronized streams in both transmit and receive directions
    - `plugins/channelrx/` — receive channel plugins for channels processing single streams in receive direction
    - `plugins/channeltx/` — transmit channel plugins for channels processing single streams in transmit direction
    - `plugins/feature/` — feature plugins providing additional functionalities not directly related to I/Q stream processing
    - `plugins/samplemimo/` — device plugins for SDR hardware supporting multiple synchronized streams in both transmit and receive directions
    - `plugins/samplesource/` — device plugins for SDR hardware receivers (sources) with single I/Q stream
    - `plugins/samplesink/` — device plugins for SDR hardware transmitters (sinks) with single I/Q stream
    - `httpserver/` — HTTP server implementation for the WebAPI
    - `logging/` — logging framework used by the application and plugins
    - `ft8/` — FT8 modem implementation as a separate module
    - `modemm17/` — M17 modem implementation as a separate module
    - `qrtplib/` — QRTPLib library for RTP protocol used by some modem plugins
    - `wdsp/` — signal processing library used by demod/modem plugins
    - `swagger/` — OpenAPI specs and generated client/server code (used to expose and consume the WebAPI)
    - `scriptsapi/` — Scripts written in Python to interact with the WebAPI
    - `doc/img/` — images used in the documentation
    - `doc/model/` — architecture diagrams and models
- Architecture notes (why things are organized this way)
  - Plugin-first design: features, device drivers and channel implementations are implemented as plugins under `plugins/`. Inspect `plugins/*/*plugin.h` and `*worker` classes for lifecycle and messaging patterns.
  - Core real-time DSP lives in `wdsp/`. Plugins call into WDSP classes (e.g. `wdsp/wcpAGC.*`, `wdsp/fmd.*`) for audio/DSP routines.
  - Swagger/OpenAPI under `swagger/` drives a generated client and server API. The code generator output for Qt lives under `swagger/sdrangel/code/qt5/` and is not meant to be hand-edited.

- Build & developer flows (concrete commands)
  - Preferred build: CMake. Preconfigured presets in `CMakePresets.json`. Typical Linux flow:
    - Configure: `cmake --preset default` (uses `build-default` and local cache variables)
    - Build: `cmake --build --preset default` or `cmake --build build-default -j$(nproc)`
    - Install (optional): `cmake --install build-default --prefix /opt/install/sdrangel`
  - For Qt6 builds use preset `default-qt6` or `default-qt6-windows` for Windows.
  - Notes: presets contain many cache variables pointing to external dependencies (`UHD_DIR`, `SoapySDR`, `LimeSuite`, `MBE_DIR`, etc.). When reproducing CI or a developer environment, set those to installed dependencies or use Docker (there is a separate `sdrangel-docker` project).

- Tests & verification
  - There are no central unit-test runners in the top-level; run small tests by building the relevant plugin or running example programs. Use `build/Makefile` targets produced by CMake.

- Common conventions and patterns
  - Message passing: many subsystems use `util/message.h` derived `Message` classes and `Msg*` naming (see `plugins/*/*plugin.h`). When adding a command or event, follow that pattern.
  - Worker threads: long-running hardware or DSP tasks are implemented as `*worker` classes and often use Qt threads (see `plugins/*/*worker.h`).
  - Generated code: files under `swagger/sdrangel/code/*` are generated by swagger-codegen; do not edit them manually. To regenerate see `swagger/sdrangel/README.md` and start the include HTTP server for includes.

- Integration points & external deps
  - Hardware/backends: plugins interface to external SDKs. Look in `CMakePresets.json` for common dependency variables (e.g., `AIRSPY_DIR`, `LIMESUITE_DIR`, `UHD_DIR`).
  - Web API: OpenAPI spec lives at `swagger/sdrangel/api/swagger/swagger.yaml`. Many plugins expose a WebAPI adapter class `*webapiadapter.cpp` which uses generated SWG classes under `swagger/sdrangel/code/qt5/client/`.
  - Scripts: automation and API helpers live in `scriptsapi/` (examples: `dump.py`, `config.py`). They show how to call the WebAPI.

- Files to inspect for common tasks (examples)
  - Add a new plugin: inspect existing `plugins/channelrx/wdsprx/` and `plugins/samplesource/*` for the plugin lifecycle, settings classes and `readme.md` documentation.
  - Debug audio/DSP: `wdsp/` (e.g., `wcpAGC.cpp`, `fmd.*`) and plugin readmes `plugins/channelrx/wdsprx/readme.md` explain AGC behavior and parameters.
  - Work with WebAPI: `swagger/sdrangel/api/swagger/swagger.yaml` + `scriptsapi/Readme.md` + `swagger/sdrangel/README.md` for generation and usage.

- Quick examples (copyable snippets agents may use)
  - Configure + build (Linux): `cmake --preset default && cmake --build --preset default -j$(nproc)`
  - Regenerate swagger Qt client (developer machine with swagger-codegen): follow `swagger/sdrangel/README.md` and run `/opt/install/swagger/swagger-codegen generate -i api/swagger/swagger.yaml -l qt5cpp -c qt5cpp-config.json -o code/qt5`

- Keep in mind
  - Do not edit generated code under `swagger/.../code/` — change the OpenAPI spec or generator configuration instead.
  - Respect plugin message naming and settings classes (`*settings.h/.cpp`) for backwards compatibility with saved session files.
  - Many device-specific behaviors are documented in `plugins/*/*/readme.md` — use them as primary references for device behavior and configuration.

If anything above is unclear or you need a different focus (for example: test harness, CI, or contribution guidelines), tell me which area to expand and I'll iterate.

## Short additions: CI, Docker, Swagger tips

- CI / reproducible builds
  - There is no single top-level CI config in the repo root — check `cmake/ci/` for CI helper scripts and the `build/` or `build-default/` directories produced by CMake to inspect test/run artifacts.
  - Use `cmake --preset default` on Linux; ensure the various *_DIR cache vars in `CMakePresets.json` are set to installed dependency locations or point to Docker images that provide them.

- Docker
  - The repo references `sdrangel-docker` in the README. For reproducible environments prefer using that project which pre-installs SDKs listed in presets.

- Swagger codegen
  - The OpenAPI spec is at `swagger/sdrangel/api/swagger/swagger.yaml`. Regenerate Qt client with the command (developer machine with generator installed):
    - `/opt/install/swagger/swagger-codegen generate -i api/swagger/swagger.yaml -l qt5cpp -c qt5cpp-config.json -o code/qt5`
  - Do not edit generated files under `swagger/sdrangel/code/*` — change the spec or generator config instead (`swagger/sdrangel/config/`).

## Where to look next (fast open targets)
- `plugins/channelrx/wdsprx/` — canonical receive channel plugin and `readme.md` explaining many signal chain choices
- `wdsp/` — DSP implementations (AGC, filters, demodulators) referenced by many plugins
- `scriptsapi/` — example scripts showing how to call the WebAPI for automation

Please review these additions and tell me if you want me to: (A) expand CI/Docker commands with example Dockerfile and Compose, (B) add a short checklist for contributing patches, or (C) generate quick search shortcuts for common code patterns.