ewsdr/doc/CAT_STATUS.md

# CAT-система EWSDR — статус реализации

Ветка разработки: `feature/cat-commands-expansion`.
Дата последнего обновления: 2026-06-26.

Документ описывает текущее состояние CAT-подсистемы EWSDR: архитектуру,
полный перечень реализованных команд, осознанные заглушки и план дальнейших
работ. За эталон протокола взят **Thetis / PowerSDR** (`CATParser.cs`,
`CATCommands.cs`, `CATStructs.xml`) — диалект Kenwood TS-2000 + расширения `ZZ*`.

---

## 1. Архитектура

```
CAT-транспорты ──► TCATEngine (парсер протокола) ──► TCATContext ──► TCATAdapter ──► TRadioController
  serial (4×)         CATEngine.pas                  (callbacks)      CATAdapter.pas      (ядро)
  TCP-сервер          разбор/формат команд                            мост, маршалинг
```

| Файл | Назначение |
|---|---|
| `CATEngine.pas` (~2270 строк) | Движок протокола: разбор `<PREFIX><SUFFIX>;`, формирование ответов, реализации всех команд Kenwood + `ZZ*`. Зависит только от RTL. |
| `CATAdapter.pas` (~445 строк) | Мост к `TRadioController`. Строит `TCATContext`: геттеры читают поля контроллера напрямую (CAT-поток, read-only), сеттеры/команды маршалятся в поток контроллера через `FController.Invoke`. Владеет движком + транспортами. |
| `CATSerial.pas` (~313 строк) | Менеджер до 4 последовательных портов (виртуальные COM-пары для rigctld/N1MM/WSJT-X). |
| `CATTcp.pas` (~507 строк) | TCP-сервер (Thetis-совместимый), управление клиентами по GUID (`ZZGA`/`ZZGR`). |

### 1.1 Принципы

- **CAT — равноправный клиент контроллера** наряду с `WebAdapter` и GUI. Никаких
  обращений к `MainForm`. Только `TRadioController`.
- **Потокобезопасность.** Геттеры читают поля контроллера напрямую (атомарное
  чтение в CAT-потоке). Сеттеры пишут параметр в scratch-поля
  (`FSyncFreq/FSyncInt/FSyncBool`) и зовут `FController.Invoke(@SyncXxx)` —
  GUI исполняет через `TThread.Synchronize`, демон — своей очередью.
- **`TCATContext`** — плоская запись callback'ов (`Get*`/`Set*`/`Do*`). Чтобы
  пробросить новую возможность контроллера в CAT, достаточно: (1) добавить
  callback в запись, (2) реализовать в адаптере геттер/сеттер/sync, (3)
  зарегистрировать в `TCATAdapter.Create`, (4) переписать тело команды в движке.
- **Формат команд:**
  ```
  SET:  <PREFIX><SUFFIX>;     (suffix = значение)
  GET:  <PREFIX>;             (suffix пустой)
  Resp: <PREFIX><VALUE>;
  Err:  ?;  (неверный формат)  |  E;  (ошибка выполнения)
  ```
  Расширенные `ZZ*` дублируют Kenwood-команды и добавляют то, чего в Kenwood нет.

### 1.2 Статистика покрытия (ZZ-команды)

| | Кол-во |
|---|---|
| Всего `ZZ*` в Thetis | 315 |
| Реально реализовано в EWSDR | **98** |
| Заглушки (отвечают валидным dummy, функции нет) | ~211 |
| Совсем не обрабатываются (вернут `?;`) | 7 |

Большинство заглушек закрыть **нечем** — в EWSDR физически отсутствует
соответствующий тракт (см. §4).

---

## 2. Что сделано

### 2.1 Реализованные команды Kenwood (одиночный префикс)

| Команда | Функция | Маппинг на контроллер |
|---|---|---|
| `FA` / `FB` | VFO A / B частота (11 цифр, Гц) | `Set/GetVfoA`, `Set/GetVfoB` |
| `FR` | приёмный VFO (0/1) | `Set/GetActiveVfo` |
| `FT` | передающий VFO / split | → `ZZSP` |
| `FW` / `SH` / `SL` | ширина фильтра (индекс пресета) | `Set/GetFilterIdx` |
| `MD` | режим (Kenwood-код) | `Set/GetMode` |
| `GT` | режим AGC (0=FAST…4=OFF) | `Set/GetAGCMode` |
| `AG` | громкость AF | `Set/GetVolume` |
| `PC` | мощность TX 0–100 % | `Set/GetDriveLevel` |
| `NB` | шумоподавитель (NB) | `Set/GetNBMode` |
| `NT` | автонотч (ANF) | `Set/GetANFEnabled` |
| `SM` | S-метр (шкала Kenwood 0000–0030) | `GetSMeter` |
| `IF` | составной статус (37 байт) | freq/mode/tx/split |
| `ID` | идентификатор (TS-2000 = 019) | const |
| `PS` | питание/состояние | `GetRunning` |
| `TX` / `RX` | передача / приём | `SetTransmitting` |
| `BU` / `BD` | смена диапазона ±1 | `DoBandUp/Down` |
| `UP` / `DN` / `RU` / `RD` | шаг настройки ±1 | `DoTuneUp/Down` |
| `SQ` | шумоподавитель FM (шкала 0–255) | `Set/GetSquelchLevel`+`On` |
| `CN` / `CT` | CTCSS тон / вкл | `Set/GetCTCSSTone`, `…On` |
| `OF` / `OS` | репитер: offset / направление | `Set/GetFMRptOffset`, `…Dir` |

### 2.2 Реализованные расширенные `ZZ*` (выборочно, наиболее значимые)

VFO/режим/фильтр: `ZZFA ZZFB ZZFI ZZFL ZZFH ZZFM ZZMD ZZFT ZZSP`,
диапазоны: `ZZBS ZZBU ZZBD ZZBA ZZBI ZZBM`,
AGC/громкость/мощность: `ZZGT ZZAG ZZPC ZZPD ZZAR`,
шумодав/нотч: `ZZNA ZZNB ZZNR ZZNS ZZNT ZZNL ZZNN`,
FM: `ZZSQ ZZSO ZZTA ZZTB ZZST`, CTUN: `ZZCN`,
S-метр/телеметрия: `ZZSM`, шаги VFO: `ZZAU ZZBP ZZSU ZZSA ZZSB`,
передача: `ZZTX ZZRX`, сервис: `ZZID ZZRV ZZGA ZZGR`.

### 2.3 Сделано в ветке `feature/cat-commands-expansion`

Все команды ниже **были заглушками** и стали рабочими — функционал в
`TRadioController` уже существовал, но не был проброшен в CAT.

**Группа 1 — Split TX**
- `ZZSP`, `FT` — split (TX на VFO-B), `FR` — выбор приёмного VFO,
  split-байт в составном `IF`.
- В `TRadioController` добавлен публичный метод `SetSplit(TxOnB)`
  (флаг `FSplitTxB` + `PushNetworkState` + `Changed(rfActiveVfo)`).
  TX-частоту радио берёт из `ActiveTXFreqHz` (учитывает split).

**Группа 2 — FM Squelch**
- `SQ` (шкала Kenwood 0–255), `ZZSQ` (0–100 %), `ZZSO` (вкл/выкл).
- Маппинг: `SetFMSquelch` / `SetFMSquelchLevel`. Уровень>0 включает
  шумоподавитель.

**Группа 3 — FM CTCSS**
- `CT`/`ZZTA` (вкл/выкл), `CN` (1-based тон 01–38), `ZZTB` (0-based 00–37).
- Маппинг: `SetFMCTCSS` / `SetFMCTCSSTone`, таблица `CTCSS_TONES[38]`.

**Группа 4 — FM-репитер**
- `OF` (offset, 9 цифр Гц), `OS` (направление).
- Трансляция направлений Kenwood (0=simplex,1=+,2=−) ↔ внутренние
  `RPT_NONE/MINUS/PLUS`. Маппинг: `SetFMRpt` / `SetFMRptOffset`.

**Группа 5 — FM tuning step**
- `ZZST` (индекс 00–03: 6.25/12.5/20/25 кГц). Маппинг: `SetFMStep`.

**Доп. команды (вторая итерация)**
| Команда | Что | Примечание |
|---|---|---|
| `ZZSO` | Squelch on/off | завершает группу squelch |
| `ZZNT` | ANF on/off | раньше ошибочно был алиасом NB |
| `ZZCN` | CTUN (click-tune) RX1 | новый callback `Get/SetCTun` → `SetCTun` |
| `ZZAR` | RX1 AGC-T / RF gain (`±nnn`) | новый callback `Get/SetAGCTop` → `SetAGCTop` (кламп 20–120 dB) |
| `ZZAU`/`ZZBP` | сдвиг VFO A/B вверх на шаг `nn` (00–14) | **исправлен баг**: были заалиашены на `ZZFA`/`ZZAP` |
| `ZZSU` | шаг активного VFO вверх | `DoTuneUp` |

Шкала шагов `ZZAU/ZZBP` — `StepIdxToHz` (зеркало Thetis `Step2Freq`):
1 Гц, 10, 25, 50, 100, 250, 500, 1к, 5к, 9к, 10к, 100к, 250к, 500к, 1 МГц.

**Новые callback'и в `TCATContext`** (этой ветки): split, squelch on/level,
CTCSS on/tone, FM repeater dir/offset, FM step, AGC-T, CTUN.

---

## 3. Что нужно сделать (актуально / есть чем закрыть)

Эти команды — заглушки, но соответствующая функция в EWSDR **уже есть** или
легко добавляется. Приоритетные кандидаты:

| Команда(ы) | Что | Чем закрыть | Сложность |
|---|---|---|---|
| `ZZCU` | загрузка CPU (read) | телеметрия процесса | низкая |
| `ZZMY` / `ZZQR` / `ZZQS` / `ZZQM` | память каналов (запись/чтение/quick) | `ChannelStore` уже есть | средняя |
| `ZZFD` | FM-девиация (radio button) | нужен публичный `SetFMDeviation` (сейчас только поле `FFMDeviation`) | низкая |
| `ZZDM` / `ZZDA` / `ZZPO` / `ZZDY` | режим/усреднение/пик/порог спектра | UI-параметры спектра | средняя |
| `ZZAS` | RX2 AGC-T | — только при появлении RX2 | — |

> Прежде чем реализовывать новую команду, сверяйся с форматом поля в
> `Thetis/.../CAT/CATStructs.xml` (`<nsetparms>` / `<ngetparms>`) и телом
> метода в `CATCommands.cs`, чтобы ширина/знак значения совпадали.

### 3.1 Совсем не обрабатываются (вернут `?;`)

`ZZCU` (CPU), `ZZDY` (DX threshold), `ZZPK`/`ZZPL` (речевой компрессор),
`ZZQA`/`ZZQB` (Quick Play/Rec), `ZZVF` (VAC stereo).
Из них реалистично добавить только `ZZCU` и (частично) `ZZDY`.

---

## 4. Осознанные заглушки (закрывать нечем)

Команды отвечают валидным dummy-значением для совместимости с управляющим ПО
(rigctld, N1MM, WSJT-X, Log4OM), но функции в EWSDR нет. Это ~70 % всех заглушек.

| Область | Команды (примеры) | Причина |
|---|---|---|
| **Второй приёмник RX2 / sub-RX** | `ZZAB ZZAS ZZBA ZZMB ZZOB`, ext `BF BG BR DO DQ DR OF OG OH OL SG SH SS` | один приёмник |
| **TX-DSP тракт** | mic gain `ZZMG`/`MG`, монитор `ZZMO`/`MO`, TX-EQ `ZZEB/ER/ET`, компрессор `ZZPK/ZZPL/CF CI CL CM`, two-tone `ZZUS`, VAC `ZZVB/ZZVF` | нет обработки передачи |
| **CW-кейер / CWX** | `ZZKM ZZKS ZZKY ZZCB ZZCD ZZCS`, `KY KS` | нет кейера |
| **RTTY / DIGI** | `ZZRA ZZRL`, ext `RF RH RM RS RY` | нет RTTY-движка |
| **RIT / XIT** | `RT XT RC RU RD` (как RIT), ext `RB RF RH` | нет смещения приёма |
| **Diversity** | `ZZDA(div) ZZDB`, ext `DA` | нет диверсити-приёма |
| **Спектр/водопад (внутр.)** | ext `SV SW SX SY SZ WT WU WV WW` | не управляется по CAT |

---

## 5. Транспорты

- **Serial** (`CATSerial.pas`): до 4 портов, параметры (порт/скорость/биты/
  чётность/стоп) из `TGlobalSettings.CATSerial*`, применяются
  `TCATAdapter.ApplySettings`. На текущей платформе сборки может быть
  `{$DEFINE CAT_SERIAL_STUB}` (см. начало файла) — проверить перед релизом.
- **TCP** (`CATTcp.pas`): сервер на `CATTcpPort`, включается флагом
  `CATTcpEnabled`. Клиенты идентифицируются GUID через `ZZGA`/`ZZGR`.

---

## 6. Как добавить новую CAT-команду (чек-лист)

1. **Сверить формат** в `CATStructs.xml` + `CATCommands.cs` (Thetis).
2. Если нужна новая возможность контроллера — есть ли публичный метод/поле
   в `TRadioController`? Если нет — добавить (по образцу `SetSplit`).
3. В `CATEngine.pas`: добавить callback(и) в `TCATContext`, `SafeGet*`-хелпер
   для GET, переписать тело команды (`CmdXX` или `ZZXX`).
4. В `CATAdapter.pas`: геттер (чтение `FController.F*`), сеттер + `SyncXX`
   (через `Invoke`), регистрация в `TCATAdapter.Create`.
5. Если команда `ZZ*` ещё не в диспетчере — добавить ветку `else if ext = '..'`.
6. Сборка-проверка: `lazbuild -B --ws=qt6 ewsdr.lpr` (GUI-граф включает CAT;
   headless-демон `ewsdrd` CAT **не** содержит).