# VDIFPacker — Pipeline

## Architecture

```{mermaid}
graph TD
    recv["mkrecv\n(SPEAD2 capture)"]
    ibuf["Input DADA\nring buffer"]
    packer["vdif_packer binary\n(FFT + VDIF pack)"]
    mq["POSIX message queue\n(mq_control)"]
    disk["Disk writer"]
    udp["UDP sender\n(jive5ab)"]

    recv -->|"float-32 heaps"| ibuf
    ibuf --> packer
    mq -->|"start/stop recording"| packer
    packer --> disk
    packer --> udp
```

<!-- AI-GENERATED:START name="pipeline_description" -->
The pipeline runs two processes sharing one PSRDADA ring buffer:

1. **mkrecv** captures `DigitalDownConverter:1` SPEAD2 heaps from the network and writes
   them into the input ring buffer.
2. **vdif_packer** reads blocks from the input buffer, applies a polyphase FFT
   (`nfft` points, `naccumulate` averages), and packs the result into VDIF frames.
   Recording is gated by a POSIX message queue (`mq_control`); the Field System
   Interface sends start/stop messages to this queue during an observation.

Output is directed to disk, to a UDP destination (e.g. jive5ab on port 4991), or both,
depending on `output_type`.

Per-channel mean and standard deviation are sampled from the vdif_packer message server and
exposed as KATCP sensors for signal quality monitoring.
<!-- AI-GENERATED:END -->

## KATCP State Machine

```{mermaid}
stateDiagram-v2
    [*] --> idle
    idle --> configuring : configure
    configuring --> configured : success
    configuring --> error : failure
    configured --> capturing : capture_start
    capturing --> running : internal
    running --> capturing : capture_stop
    capturing --> configured : stop
    configured --> idle : deconfigure
    error --> idle : reset
```

## Configuration

```{include} ../generated/vdif_packer/config_table.md
```

### Notes

- `thread_ids` must be a comma-separated string of VDIF thread IDs matching the number of
  input channels divided by the number of threads.
- `mq_control` is the POSIX message queue name; the Field System Interface writes to this
  queue to gate recording.
- `output_type` accepts `"disk"`, `"network"`, or both.
- `udp.dest_port` defaults to `4991`, which is jive5ab's standard VDIF UDP receive port.
- `nfft` and `naccumulate` control the spectral transform applied before VDIF packing.

## KATCP Sensors

| Sensor | Type | Description |
|---|---|---|
| `pipeline-status` | string | State machine state |
| `current-config` | string | Active configuration as JSON |
| `pipeline-version` | string | Package version |
| `edd-core-version` | string | edd-core package version |
| `vdif-channel-mean` | string | Per-channel mean (JSON array) |
| `vdif-channel-stddev` | string | Per-channel standard deviation (JSON array) |
| `recording-state` | string | `idle` or `recording` |
| `sending-state` | string | `idle` or `sending` |
| `current-files` | string | List of currently open output files |