###############
Getting Started
###############

This is a practical reference for the ``ria`` CLI from ``ria-toolkit-oss``.

**Scope of this guide:**

* **Installation and SDR driver prerequisites** — how to install RIA Toolkit OSS and configure the system drivers your hardware requires
* **End-to-end CLI workflow** — a step-by-step walkthrough from hardware discovery through capture, annotation, and processing
* **Full command reference** — options, flags, and examples for every ``ria`` command
* **Python scripting preview** — using the toolkit API directly without the CLI

**Official resources:**

* `Project README <https://riahub.ai/qoherent/ria-toolkit-oss>`_
* `Documentation <https://ria-toolkit-oss.readthedocs.io/>`_
* `PyPI package <https://pypi.org/project/ria-toolkit-oss/>`_
* `RIA Hub Conda package <https://riahub.ai/qoherent/-/packages/conda/ria-toolkit-oss>`_


1) Installation and Setup
==========================

Before using the ``ria`` CLI, follow the :doc:`Installation <installation>` guide to
install RIA Toolkit OSS and any SDR drivers required for your hardware.


1.1 SDR driver prerequisites
-----------------------------

Toolkit package install does not install all system SDR drivers. Install vendor/runtime
dependencies for the hardware you use.

Examples (depends on device and OS):

.. list-table::
   :widths: 25 75
   :header-rows: 1

   * - Device
     - Driver Package
   * - USRP
     - UHD drivers
   * - Pluto
     - libiio / IIO utilities
   * - BladeRF
     - libbladeRF
   * - HackRF
     - libhackrf
   * - RTL-SDR
     - librtlsdr

See repo docs under ``docs/source/sdr_guides/*`` and your OS package instructions.


2) CLI Structure
=================

Top-level CLI follows this model:

.. code-block:: bash

   ria [GLOBAL_OPTS] <command> [ARGS] [OPTIONS]

**Global:**

* ``-v, --verbose`` (defined on root click group)

**Top-level commands:**

.. list-table::
   :widths: 25 75
   :header-rows: 1

   * - Command
     - Purpose
   * - :ref:`discover <cmd-discover>`
     - Probe SDR drivers and enumerate attached hardware
   * - :ref:`init <cmd-init>`
     - Create and manage user metadata defaults
   * - :ref:`capture <cmd-capture>`
     - Record IQ samples from a connected SDR
   * - :ref:`view <cmd-view>`
     - Generate visualizations from IQ files
   * - :ref:`annotate <cmd-annotate>`
     - Label signal regions manually or with auto-detection (group)
   * - :ref:`convert <cmd-convert>`
     - Convert between IQ file formats
   * - :ref:`split <cmd-split>`
     - Split, trim, or extract recordings
   * - :ref:`combine <cmd-combine>`
     - Merge multiple recordings by concatenation or addition
   * - :ref:`generate / synth <cmd-generate>`
     - Generate synthetic IQ signals (group; ``synth`` is an alias)
   * - :ref:`transform <cmd-transform>`
     - Apply augmentations or impairments to recordings (group)
   * - :ref:`transmit <cmd-transmit>`
     - Transmit IQ through a TX-capable SDR


3) Quick End-to-End Workflow
=============================

3.1 Discover radios
--------------------

Run this first in any new environment to verify drivers and detect hardware before
attempting RX/TX commands.

.. code-block:: bash

   ria discover
   ria discover -v
   ria discover --json-output


3.2 Initialize local metadata defaults
---------------------------------------

Set reusable metadata once so generated/captured files automatically include consistent
provenance fields.

.. code-block:: bash

   ria init
   ria init --author "Jane Doe" --project "rf-campaign-1" --location "Lab-A"  # non-interactive
   ria init --show  # show config


3.3 Capture IQ
---------------

Capture baseband data from a connected SDR into a reusable file format.

.. code-block:: bash

   ria capture -d pluto -f 2.44G -s 2e6 -n 500000 -o capture.sigmf-data


3.4 Visualize and inspect
--------------------------

Render quick diagnostic plots to validate signal presence, quality, and rough structure.

.. code-block:: bash

   ria view capture.sigmf-data --type simple
   ria view capture.sigmf-data --type full --show --no-save


3.5 Auto-annotate and inspect annotations
------------------------------------------

Create initial labels automatically, then inspect annotation objects before downstream use.

.. code-block:: bash

   ria annotate energy capture.sigmf-data --label signal --threshold 1.2
   ria annotate list capture.sigmf-data --verbose


3.6 Convert and split
----------------------

Normalize file format and split large captures into manageable chunks for processing or
training.

.. code-block:: bash

   ria convert capture.sigmf-data capture.npy
   ria split capture.sigmf-data --split-every 100000 --output-dir chunks


3.7 Apply transforms
---------------------

Augment or impair recordings to produce controlled variants.

.. code-block:: bash

   ria transform augment channel_swap capture.npy
   ria transform impair add_awgn_to_signal capture.npy --params snr=10


3.8 Transmit (TX-capable radios only)
--------------------------------------

Replay recorded or synthesized IQ through a transmit-capable SDR.

.. code-block:: bash

   ria transmit -d hackrf -f 2.44G -s 2e6 --input capture.sigmf-data
   ria transmit -d hackrf --generate lfm --continuous  # generated waveform


4) Command Reference
=====================

.. _cmd-discover:

4.1 ``discover``
-----------------

**Purpose:**

* Probe available SDR drivers and enumerate attached hardware.
* Confirm whether runtime libraries/drivers are installed and discoverable before
  capture/transmit.

**Usage:**

.. code-block:: bash

   ria discover [--verbose] [--json-output]

**Options:**

* ``-v, --verbose``: include per-driver probe details and import/init failures.
* ``--json-output``: emit JSON (useful for automation and inventory scripts).

**Behavior notes:**

* ``discover`` checks multiple backends (USB and network paths, depending on driver support).
* A device not appearing here usually means one of: missing system driver, permission issue,
  USB/network connectivity issue.
* Use ``--verbose`` first when troubleshooting; it surfaces driver-level failures that are
  hidden in default output.


.. _cmd-init:

4.2 ``init``
-------------

**Purpose:**

* Create/manage user config file (defaults to ``~/.ria/config.yaml``, or
  ``$XDG_CONFIG_HOME/ria/config.yaml``).

**Usage:**

.. code-block:: bash

   ria init [options]

**Key options:**

*Metadata defaults:*
``--author``, ``--organization``, ``--project``, ``--location``, ``--testbed``,
``--license``, ``--hw``, ``--dataset``

*Actions:*
``--show``, ``--reset``

*Control:*
``--config-path``, ``--interactive`` / ``--no-interactive``, ``-y`` / ``--yes``

**What each option category does:**

* Metadata defaults (``--author``, ``--project``, etc.): stored once and reused for later
  recordings so files have consistent provenance.
* SigMF-focused fields (``--license``, ``--hw``, ``--dataset``): populate metadata commonly
  expected in shared datasets.
* ``--show``: read-only inspect of the current resolved config.
* ``--reset``: remove config and start clean.
* ``--config-path``: use a non-default config location (useful for isolated environments or
  CI).
* ``--interactive`` / ``--no-interactive``: force prompts on or off regardless of terminal
  auto-detection.
* ``--yes``: suppress confirmation prompts for scripted runs.

.. note::
   Current command output includes a note that some config integration is still being
   finalized. Config values are already consumed by multiple commands (capture, convert,
   generate metadata, and YAML config loading paths).


.. _cmd-capture:

4.3 ``capture``
----------------

**Purpose:**

* Record IQ samples from a supported SDR and save to ``sigmf``, ``npy``, ``wav``, or
  ``blue``.

**Usage:**

.. code-block:: bash

   ria capture [options]

Device selection (``--device``) is optional if only one device is detected. Exactly one of
``--num-samples`` or ``--duration`` is required.

**Core options:**

*Device/connection:*

* ``-d, --device {pluto,hackrf,bladerf,usrp,rtlsdr,thinkrf}``
* ``-i, --ident``
* ``-c, --config <yaml>``

*RF/capture:*

* ``-s, --sample-rate``
* ``-f, --center-frequency`` (supports values like ``915e6``, ``2.4G``)
* ``-g, --gain``
* ``-b, --bandwidth``
* ``-n, --num-samples``
* ``-t, --duration``

*Output:*

* ``-o, --output``
* ``--output-dir``
* ``--format {npy,sigmf,wav,blue}``
* ``--save-image``

*Metadata/logging:*

* ``-m, --metadata KEY=VALUE`` (repeatable)
* ``-v, --verbose``, ``-q, --quiet``

**How options work in practice:**

* ``--device`` + ``--ident``: select both device class and target instance; ``--ident``
  takes serial/IP style selectors.
* ``--config``: load a YAML option set, then override specific fields on the CLI as needed.
* ``--num-samples`` vs ``--duration``: use exact sample count for deterministic datasets,
  or time-based capture for quick acquisition.
* ``--format``: ``sigmf`` is best for metadata/annotation workflows.
* ``--save-image``: writes a quick visual summary alongside capture output.
* ``--metadata KEY=VALUE``: injects run-specific metadata (campaign ID, antenna, scenario
  tag, etc.).

**Output behavior:**

* If ``--output`` is omitted, a timestamped filename is generated automatically.
* If ``--output-dir`` is omitted, captures default to ``recordings/``.
* Format is inferred from the ``--output`` extension when no explicit ``--format`` is given.

**Examples:**

.. code-block:: bash

   ria capture -d hackrf -s 2e6 -f 2.44G -n 1000000 -o rf.sigmf-data
   ria capture -d pluto -f 915e6 -t 2 --format npy --output-dir recordings
   ria capture -c capture_config.yaml


.. _cmd-view:

4.4 ``view``
-------------

**Purpose:**

* Generate visualizations from IQ files.
* Quickly validate signal quality, occupancy, and annotation coverage without writing custom
  plotting code.

**Usage:**

.. code-block:: bash

   ria view <input> [options]

``<input>`` accepts SigMF, NPY, WAV, and Blue files.

**Mode** (``--type``):

* ``simple``: fast-look plots for sanity checks and quick iteration.
* ``full``: multi-panel diagnostic figure (IQ, time, frequency, metadata views).
* ``annotations`` / ``annotation``: render annotation overlays.
* ``channels``: channelized/segmented visualization.
* ``annotate``: convenience path used in some annotation workflows.

**Output/display options:**

* ``--output``, ``--format {png,pdf,svg,jpg}``
* ``--show``: open an interactive window (requires a GUI display environment).
* ``--no-save``: suppress file output; only meaningful with ``--show``.
* ``--overwrite``

**Style options:**

* ``--dpi``, ``--figsize WxH``, ``--title``
* ``--light``: switch to a light theme (useful for reports/slides).

**Loading options:**

* ``--legacy``: force legacy NPY loading path for older datasets.
* ``--config``

**Mode-specific options:**

*simple:* ``--fast``, ``--compact``, ``--horizontal``, ``--constellation``, ``--labels``,
``--slice start:end[:step]``

*full:* ``--plot-length``, ``--no-spectrogram``, ``--no-iq``, ``--no-frequency``,
``--no-constellation``, ``--no-metadata``, ``--no-logo``, ``--spines``

*annotations/channels:* ``--channel``

**Examples:**

.. code-block:: bash

   ria view capture.sigmf-data --type simple
   ria view capture.npy --type full --title "Test Capture" --format pdf
   ria view capture.npy --show --no-save
   ria view old.npy --legacy --type simple
   ria view recordings\qam64_35.npy --type simple
   ria view recordings\qam64_35.npy --type full

.. figure:: ../images/recordings/qam64_35.png
   :alt: Example output of ria view recordings\qam64_35.npy --type simple

   Output of ``ria view recordings\qam64_35.npy --type simple``

.. figure:: ../images/recordings/qam64_35-full.png
   :alt: Example output of ria view recordings\qam64_35.npy --type full

   Output of ``ria view recordings\qam64_35.npy --type full``


.. _cmd-annotate:

4.5 ``annotate`` group
-----------------------

**Purpose:**

* Manual annotation management and auto-detection/separation.
* Build or refine label metadata directly in recordings for downstream training, QA, and
  filtering.

**Command shape:**

.. code-block:: bash

   ria annotate <subcommand> ...

**Subcommands:**

.. list-table::
   :widths: 25 75
   :header-rows: 1

   * - Subcommand
     - Purpose
   * - ``list``
     - Inspect all annotations on a recording
   * - ``add``
     - Add one annotation with explicit sample-domain bounds
   * - ``remove``
     - Remove one annotation by index
   * - ``clear``
     - Remove all annotations from a recording
   * - ``energy``
     - Auto-detect regions above the estimated noise floor
   * - ``cusum``
     - Auto-detect regime changes using change-point detection
   * - ``threshold``
     - Auto-detect regions using normalized magnitude thresholding
   * - ``separate``
     - Decompose annotations into narrower spectral components

**General behavior:**

* SigMF is the preferred format for durable annotation metadata.
* For non-SigMF input, many operations write a new output artifact unless overwrite behavior
  is explicitly requested.
* ``--type {standalone,parallel,intersection}`` controls annotation relation semantics.

``ria annotate list``
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   ria annotate list <input> [--verbose]

Prints all annotations for a recording in index order. ``--verbose`` includes additional
detail per record.

``ria annotate add``
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   ria annotate add <input> --start <int> --count <int> --label <text> [options]

Adds one explicit annotation with sample-domain boundaries.

* ``--start``: first sample index of the annotated region.
* ``--count``: number of samples in the region.
* ``--freq-lower``, ``--freq-upper``: optional spectral bounds in Hz.
* ``--comment``, ``--type``, ``-o`` / ``--output``, ``--overwrite``, ``--quiet``

``ria annotate remove``
~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   ria annotate remove <input> <index> [--output ...] [--overwrite] [--quiet]

Removes exactly one annotation by list index. Run ``annotate list`` first to confirm the
index.

``ria annotate clear``
~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   ria annotate clear <input> [--force] [--overwrite] [--quiet]

Removes all annotations from the recording. ``--force`` bypasses the confirmation prompt.

``ria annotate energy``
~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   ria annotate energy <input> [options]

Detects energetic regions above the estimated noise floor and writes them as annotations.

* ``--label``
* ``--threshold``: noise-floor multiplier; higher values reduce false positives but can miss
  weak signals.
* ``--segments``: number of segments used to estimate baseline noise.
* ``--window-size``: smoothing size; larger windows stabilize detections at the cost of
  sharp transition precision.
* ``--min-distance``: minimum sample spacing between detections, preventing dense duplicate
  regions.
* ``--freq-method {nbw,obw,full-detected,full-bandwidth}``: how frequency bounds are assigned
  to annotations.
* ``--nfft``, ``--obw-power``
* ``--type``, ``-o`` / ``--output``, ``--overwrite``, ``--quiet``

``ria annotate cusum``
~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   ria annotate cusum <input> [options]

Uses change-point detection (CUSUM-style logic) to find regime changes and annotate
contiguous segments.

* ``--label``
* ``--min-duration`` (ms): prevents tiny over-segmented labels.
* ``--window-size``
* ``--tolerance``: merges nearby boundaries when set above default.
* ``--type``, ``-o`` / ``--output``, ``--overwrite``, ``--quiet``

``ria annotate threshold``
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   ria annotate threshold <input> --threshold <0.0..1.0> [options]

Uses normalized magnitude thresholding to derive annotation spans. Use where a fixed
amplitude threshold is sufficient.

* ``--label``, ``--window-size``, ``--type``, ``-o`` / ``--output``, ``--overwrite``,
  ``--quiet``

``ria annotate separate``
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   ria annotate separate <input> [options]

Decomposes selected annotations into narrower spectral components and emits refined
annotations.

* ``--indices "0,1,2"``: limit operation to specific annotations; omit to process all.
* ``--nfft``: larger FFT improves frequency resolution but increases compute time.
* ``--noise-threshold-db``: stabilizes detection across heterogeneous captures.
* ``--min-component-bw``: rejects narrow fragments likely to be noise artifacts.
* ``-o`` / ``--output``, ``--overwrite``, ``--quiet``, ``--verbose``

**Examples:**

.. code-block:: bash

   ria annotate list capture.sigmf-data --verbose
   ria annotate add capture.sigmf-data --start 10000 --count 5000 --label burst
   ria annotate energy capture.sigmf-data --label signal --threshold 1.3
   ria annotate cusum capture.sigmf-data --min-duration 5
   ria annotate threshold recordings/sample_recording3.npy --threshold 0.7 --label 70%
   ria annotate separate capture.sigmf-data --indices 0,1 --verbose

.. figure:: ../images/recordings/sample_recording3_annotated.png
   :alt: Example output of ria annotate threshold recordings/sample_recording3.npy --threshold 0.7 --label 70%

   Output of ``ria annotate threshold recordings/sample_recording3.npy --threshold 0.7 --label 70%``


.. _cmd-convert:

4.6 ``convert``
----------------

**Purpose:**

* Convert between ``sigmf``, ``npy``, ``wav``, and ``blue``.
* Normalize datasets into the format required by downstream tooling or collaboration targets.

**Usage:**

.. code-block:: bash

   ria convert <input> [output] [options]

If ``output`` is omitted, ``--format`` must be provided. If both are given, format is
inferred from the output file extension.

**Options:**

* ``--format {npy,sigmf,wav,blue}``
* ``--output-dir``
* ``--legacy``: use older NPY loader behavior for historical recordings.
* ``--wav-sample-rate``: target sample rate for WAV export.
* ``--wav-bits {16,32}``: output PCM depth; higher preserves more dynamic range.
* ``--blue-format {CI,CF,CD}``: Bluefile complex sample representation.
* ``--metadata KEY=VALUE`` (repeatable): add or override metadata during conversion;
  especially useful when exporting to SigMF.
* ``--overwrite``, ``-v`` / ``--verbose``, ``-q`` / ``--quiet``

**Examples:**

.. code-block:: bash

   ria convert recording.sigmf-data output.npy
   ria convert recording.npy --format sigmf
   ria convert highrate.npy audio.wav --wav-sample-rate 48000
   ria convert old.npy --format sigmf --legacy --overwrite


.. _cmd-split:

4.7 ``split``
--------------

**Purpose:**

* Split, trim, or extract recordings.
* Create manageable dataset shards or extract windows of interest without custom scripts.

**Usage:**

.. code-block:: bash

   ria split <input> [operation] [options]

Choose exactly one operation per invocation:

* ``--split-at <sample>``: binary split at a specific sample index.
* ``--split-every <N>``: fixed-size chunking for ML pipelines.
* ``--split-duration <seconds>``: time-based chunking.
* ``--trim`` (with ``--start`` + ``--length`` or ``--end``): extract one sub-window.
* ``--extract-annotations``: write each annotated region as a standalone file.

**Trim controls:** ``--start``, ``--length``, ``--end``

**Annotation extraction filters:** ``--annotation-label``, ``--annotation-index``

**Output controls:**
``--output-dir``, ``--output-prefix``, ``--output-format {npy,sigmf,wav,blue}``,
``--overwrite``, ``--legacy``, ``-v`` / ``--verbose``, ``-q`` / ``--quiet``

**Examples:**

.. code-block:: bash

   ria split recording.sigmf-data --split-at 500000 --output-dir out
   ria split recording.sigmf-data --split-every 100000 --output-dir chunks
   ria split recording.sigmf-data --split-duration 1.0 --output-dir chunks
   ria split recording.npy --trim --start 1000 --length 5000 --output-dir trimmed
   ria split annotated.sigmf-data --extract-annotations --annotation-label payload


.. _cmd-combine:

4.8 ``combine``
----------------

**Purpose:**

* Merge multiple recordings by concatenation or sample-wise addition.
* Assemble multi-part captures or synthesize mixtures for testing and model training.

**Usage:**

.. code-block:: bash

   ria combine <input1> <input2> [input3 ...] <output> [options]

**Options:**

* ``--mode {concat,add}``
* ``--align-mode {error,truncate,pad,pad-start,pad-center,pad-end,repeat,repeat-spaced}``
* ``--pad-start-sample``, ``--repeat-spacing``
* ``--normalize``: rescale combined output to avoid clipping/saturation after addition.
* ``--output-format {sigmf,npy,wav,blue}``
* ``--overwrite``, ``--metadata KEY=VALUE`` (repeatable)
* ``--legacy``, ``--verbose``, ``--quiet``

**Mode semantics:**

* ``concat``: append inputs sequentially in time.
* ``add``: sample-wise summation — all inputs must be aligned to the same length.

**Alignment options for** ``--mode add``:

* ``error``: fail if lengths differ.
* ``truncate``: cut all to shortest length.
* ``pad``, ``pad-start``, ``pad-center``, ``pad-end``: zero-pad shorter streams.
* ``repeat``: tile shorter streams to match longest.
* ``repeat-spaced``: repeated placement with spacing via ``--repeat-spacing``.

**Examples:**

.. code-block:: bash

   ria combine a.npy b.npy c.npy merged.npy
   ria combine signal.npy noise.npy noisy.npy --mode add
   ria combine long.npy short.npy out.npy --mode add --align-mode pad-center
   ria combine signal.npy pattern.npy out.npy --mode add --align-mode repeat-spaced --repeat-spacing 10000


.. _cmd-generate:

4.9 ``generate`` group (and ``synth`` alias)
---------------------------------------------

**Purpose:**

* Generate synthetic IQ signals and save in ``npy``, ``sigmf``, ``wav``, or ``blue``.
* Create known-reference waveforms and synthetic datasets for validation, demos, and ML
  data generation.

``ria synth ...`` is an alias for ``ria generate ...``.

**Usage:**

.. code-block:: bash

   ria generate <subcommand> [subcommand options] [common options]

**Available subcommands:**

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Subcommand(s)
     - Description
   * - ``tone``
     - Clean sinusoidal calibration/reference source
   * - ``noise``
     - Baseline noise floor data or controlled additive-noise synthesis
   * - ``chirp``
     - Sweep-based radar/sonar-style signals and bandwidth occupancy tests
   * - ``square``, ``sawtooth``
     - Periodic waveform primitives
   * - ``qam``, ``apsk``, ``pam``, ``psk``
     - Digital modulation families with pulse-shaping filter support
   * - ``fsk``
     - Frequency-shift keying with configurable tone spacing
   * - ``ook``, ``oqpsk``, ``gmsk``
     - On-off keying and continuous-phase modulation schemes

**Common options shared across all generators:**

* ``-s, --sample-rate`` (required)
* ``-n, --num-samples`` or ``-t, --duration``
* ``--frequency-shift``, ``-fc`` / ``--center-frequency``
* ``--add-noise``, ``--noise-power``, ``--path-gain``
* ``-o, --output`` (required), ``-F`` / ``--format {npy,sigmf,wav,blue}``
* ``--multipath-paths``, ``--multipath-max-delay``
* ``--iq-amp-imbalance``, ``--iq-phase-imbalance``, ``--iq-dc-offset``
* ``--config <yaml>``
* ``-w`` / ``--overwrite``, ``-m`` / ``--metadata KEY=VALUE`` (repeatable)
* ``-v`` / ``--verbose``, ``-q`` / ``--quiet``

``--frequency-shift`` and ``--center-frequency`` let you separate the baseband shape from
RF metadata context. ``--add-noise`` and ``--noise-power`` apply post-generation noise.
Multipath and IQ imbalance flags apply impairment-style post-processing during generation.

``tone``
~~~~~~~~~

Options: ``--frequency``, ``--amplitude``, ``--phase``

``noise``
~~~~~~~~~~

Options: ``--noise-type {gaussian,uniform}``, ``--power``

``chirp``
~~~~~~~~~~

Options: ``--bandwidth`` (required), ``--period`` (required), ``--type {up,down,up_down}``

``square``
~~~~~~~~~~~

Options: ``--frequency``, ``--amplitude``, ``--duty-cycle``, ``--phase``

``sawtooth``
~~~~~~~~~~~~~

Options: ``--frequency``, ``--amplitude``, ``--phase``

Digital modulation families: ``qam``, ``apsk``, ``pam``, ``psk``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ``--symbols``, ``--order``
* ``--symbol-rate``
* ``--filter {rrc,rc,gaussian,none}``, ``--filter-span``, ``--filter-beta``
* ``--message-source {random,file,string}``, ``--message-content``

Use ``--message-source random`` for synthetic datasets, ``file`` for deterministic replay,
or ``string`` for small human-readable payload testing. Pulse-shaping filter options
(``--filter``, ``--filter-span``, ``--filter-beta``) control spectral occupancy and ISI.

``fsk``
~~~~~~~~

Options: ``--symbols``, ``--order``, ``--symbol-rate``, ``--freq-spacing``,
``--modulation-index``, ``--message-source``, ``--message-content``

``--freq-spacing`` and ``--modulation-index`` drive tone separation and spectral profile.

``ook``, ``oqpsk``, ``gmsk``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Options: ``--symbol-rate`` (required), ``--message-source {random,file,string}``,
``--message-content``; ``gmsk`` also accepts ``--bt``

``gmsk --bt`` sets the Gaussian filter bandwidth-time product (spectral compactness vs
symbol transition sharpness).

**Examples:**

.. code-block:: bash

   ria generate tone -s 2e6 -n 500000 --frequency 50e3 -o tone.sigmf-data
   ria generate noise -s 2e6 -n 500000 --noise-type gaussian --power 0.05 -o noise.npy
   ria generate chirp -s 5e6 -t 0.5 --bandwidth 2e6 --period 0.01 --type up -o chirp.sigmf-data
   ria generate qam -s 2e6 -r 100e3 -M 16 -N 5000 --message-source random -o qam16.npy
   ria synth psk -s 2e6 -r 100e3 -M 8 -N 8000 -o psk8.npy


.. _cmd-transform:

4.10 ``transform`` group
-------------------------

**Purpose:**

* Apply algorithmic transforms to existing recordings.
* Run reusable augmentations/impairments for dataset diversity and robustness testing.

**Usage:**

.. code-block:: bash

   ria transform <augment|impair|custom> ...

``augment``
~~~~~~~~~~~~

.. code-block:: bash

   ria transform augment [augmentation] [input] [output] [options]

Applies transforms from ``iq_augmentations`` (dataset-expansion style modifications).

Options: ``--list``, ``--help-transform``, ``--params KEY=VALUE`` (repeatable), ``--view``,
``--overwrite``, ``-v`` / ``--verbose``, ``-q`` / ``--quiet``

``impair``
~~~~~~~~~~~

.. code-block:: bash

   ria transform impair [impairment] [input] [output] [options]

Applies transforms from ``iq_impairments`` (noise, distortion, and channel degradation
effects). Same options as ``augment``.

``custom``
~~~~~~~~~~~

.. code-block:: bash

   ria transform custom [transform_name] [input] [output] --transform-dir <dir> [options]

Dynamically loads public functions from Python files in ``--transform-dir`` and exposes them
as callable transforms.

Options: ``--transform-dir`` (required), ``--list``, ``--help-transform``,
``--params KEY=VALUE`` (repeatable), ``--view``, ``--overwrite``, ``-v`` / ``--verbose``,
``-q`` / ``--quiet``

``--params`` values must be ``KEY=VALUE``; types are inferred as int, float, or string.
Use ``--list`` to enumerate available transform names, and ``--help-transform <name>`` to
inspect parameter hints. ``--view`` writes a PNG preview alongside transform output.

**Examples:**

.. code-block:: bash

   ria transform augment --list
   ria transform augment channel_swap in.npy out.npy
   ria transform augment drop_samples in.npy --params max_section_size=5 --view

   ria transform impair --list
   ria transform impair add_awgn_to_signal in.npy out.npy --params snr=10

   ria transform custom --transform-dir ./my_transforms --list
   ria transform custom my_filter in.npy out.npy --transform-dir ./my_transforms --params cutoff=0.2


.. _cmd-transmit:

4.11 ``transmit``
------------------

**Purpose:**

* Transmit IQ via a TX-capable SDR (``pluto``, ``hackrf``, ``bladerf``, ``usrp``).
* Support playback of captured/generated waveforms for over-the-air or wired-loop test
  scenarios.

**Usage:**

.. code-block:: bash

   ria transmit [options]

**Input source (choose one):**

* ``--input <file>``: transmit an existing recording.
* ``--generate {lfm,chirp,sine,pulse}``: synthesize a transmit signal on the fly.
* If neither is specified, the command defaults to a generated LFM waveform.

**Core options:**

*Device/radio:* ``-d`` / ``--device {pluto,hackrf,bladerf,usrp}``, ``-i`` / ``--ident``,
``-c`` / ``--config``

*RF:* ``-s`` / ``--sample-rate``, ``-f`` / ``--center-frequency``, ``-g`` / ``--gain``,
``-b`` / ``--bandwidth``

*Input/gen:* ``--input``, ``--legacy``, ``--generate {lfm,chirp,sine,pulse}``

*TX control:*

* ``-r, --repeat``
* ``--continuous``: transmit until interrupted (``Ctrl+C``).
* ``--tx-delay``: pause between repeats when ``--repeat`` is used.
* ``-y, --yes``: skip confirmation prompts; use carefully in scripted environments.

*Logging:* ``-v`` / ``--verbose``, ``-q`` / ``--quiet``

.. warning::
   ``--continuous`` transmits until manually interrupted. Validate gain settings, antenna
   configuration, and regulatory compliance before use.

**Examples:**

.. code-block:: bash

   ria transmit -d pluto -f 915e6 -s 2e6 --input capture.sigmf-data
   ria transmit -d hackrf --generate lfm -f 2.44G --continuous
   ria transmit -d usrp --input msg.npy -r 3 --tx-delay 0.5


5) YAML Config Patterns
========================

Several commands accept ``--config <file.yaml>`` for parameter loading. CLI flags generally
override values loaded from ``--config``.

Keep one stable baseline YAML per workflow (capture, generate, transmit), then override only
experiment-specific fields on the CLI.

**Capture config example:**

.. code-block:: yaml

   device: pluto
   ident: 192.168.2.1
   sample_rate: 2000000
   center_frequency: 2.44G
   gain: 20
   bandwidth: 2000000
   num_samples: 500000
   format: sigmf
   output: run1.sigmf-data
   metadata:
     campaign: lab_eval
     antenna: dipole

.. code-block:: bash

   ria capture -c capture.yaml

**Generate config example:**

.. code-block:: yaml

   sample_rate: 2000000
   num_samples: 200000
   format: npy
   output: synth.npy
   noise_power: 0.02

.. code-block:: bash

   ria generate noise --config generate.yaml


6) Version Notes
=================

These notes are based on the current implementation and should be re-validated against future
releases.

1. Some command docstrings and examples still mention ``utils`` or ``ria_toolkit_oss``
   command prefixes in text blocks. The operational command is ``ria ...``.
2. Command bindings currently import ``viewe`` instead of ``view`` in
   ``src/ria_toolkit_oss_cli/ria_toolkit_oss/commands.py``.
3. Multiple non-CLI modules still import ``utils.*``, which can create runtime dependency
   coupling when using only ``ria-toolkit-oss`` in isolation.

.. tip::
   If you observe unexpected import errors after install, check the package version and
   changelog, then test ``ria --help`` in a clean virtual environment.


7) Brief Scripting (Python) Preview
=====================================

For quick non-CLI use:

.. code-block:: python

   from ria_toolkit_oss.data import Recording
   from ria_toolkit_oss.io import load_recording, to_sigmf
   from ria_toolkit_oss.transforms import iq_augmentations, iq_impairments

   rec = load_recording("capture.sigmf-data")
   aug = iq_augmentations.channel_swap(rec)
   imp = iq_impairments.add_awgn_to_signal(aug, snr=10)
   to_sigmf(imp, filename="capture_awgn", path=".")

You can also call annotation algorithms and block-generator primitives from Python directly.
