Wiki SDR SA PRO

Webhook, MQTT і локальний REST

PRO «Сканер» віддає свої тривоги іншим програмам трьома шляхами: надсилає кожну тривогу HTTP-запитом на вашу адресу (webhook), публікує її у ваш брокер MQTT і показує свій стан локальним сервером REST лише для читання на цьому самому комп’ютері. Усе це типово вимкнене, і програма з’єднується лише з адресами, які ви ввели самі. На цій сторінці — де ці вимикачі, що саме йде мережею, які межі й відмови. Самі тривоги описано на сторінці Таблиця частот і тривоги, решту дій за тривогою — на сторінці Зони тривоги й дії за тривогою.

Що й куди йде 0.9.58

Webhook: Прапорець Webhook (HTTP POST) і поле адреси — у згортці Дії за тривогою списку Таблиця частот: N. На кожну нову тривогу — запит POST із JSON на цю адресу. Див. нижче.
MQTT: Блок MQTT у згортці Наскільки списку вірити списку Сигнали: N: прапорець Публікувати тривоги, брокер, тема, ім’я й пароль. Кожна тривога — повідомлення в тему брокера. Див. нижче.
Локальний REST: Блок Локальний REST у тій самій згортці: прапорець Віддавати стан по HTTP і порт. Цей сервер нічого не надсилає сам — лише відповідає на запити програм із цього комп’ютера. Див. нижче.

Типово вимкнено все. Прапорці, адреси, порт і тема зберігаються між запусками у файлі settings.json «Сканера» (див. Що зберігається між запусками). Webhook і MQTT, увімкнені перед виходом, діють і після наступного запуску; сервер REST — ні: після кожного запуску він стоїть, доки ви знову не поставите прапорець.
Сама програма в інтернет не ходить. Мережею SDR SA PRO з’єднується лише там, де це налаштували ви: з приймачем Pluto, з адресою webhook і з брокером MQTT. Див. також Мережа.
Мережею йде лише тривога. Webhook, MQTT і шлях /alarms локального REST несуть її тим самим JSON (нижче): частота, ширина, рівень, час, причина й клас за таблицею частот.
Лише ефір. Для запису з файлу й демонстраційного сигналу тривог немає, тож і надсилати нічого.
На кожній станції — своє. Коли у вікні кілька станцій, у кожної свій «Сканер» зі своїми налаштуваннями, а отже, свій webhook, своє з’єднання MQTT і свій сервер REST. Тіло тривоги не каже, з якої вона станції. Двом станціям потрібні різні порти REST — на зайнятому порту сервер не стане — і бажано різні теми MQTT, інакше стан online/offline обох ляже в одну тему. Дві станції з одним брокером ще не перевіряли. Див. «Сканер» на кількох станціях.

Тіло тривоги

Тривога — об’єкт JSON у кодуванні UTF-8. Поля ті самі, що в журналі подій, лише числами:

Поле	Що в ньому
`event`	`alarm`; для «Проби» — `test`
`program`	`SDR-SA-PRO`
`time_utc`	Час виміру, у якому рядок уперше підпав під правило, UTC до секунди: `2026-11-03T10:40:00Z`
`frequency_hz`	Центр рядка, Гц
`f_lo_hz`, `f_hi_hz`	Нижній і верхній край рядка, Гц
`width_hz`	Ширина рядка, Гц
`level_db`	Рівень у дБ над місцевою полицею, один знак після крапки; `null` — рівня немає
`reason`	Причина: `guard`, `watch`, `kind` або `video`
`name`, `kind`	Клас за таблицею частот: назва й тип ділянки; порожньо — сигнал не лежить у жодній
`number`	Порядковий номер тривоги від початку списку, з одиниці
`channel`	Номер каналу; `0` — рядок не канал
`video`	`PAL` чи `NTSC`, коли відео підтвердив пошук відеоканалів; інакше порожньо

Поля what журналу подій (сигнал чи ділянка активності) у тілі немає.

Webhook 0.9.58

На вкладці Сканер перейдіть до списку Таблиця частот: N, розгорніть згортку Дії за тривогою і поставте прапорець Webhook (HTTP POST); у поле поруч впишіть адресу, наприклад http://192.168.1.20:8080/alarm. Поки прапорець стоїть, під ним видно підказку: що саме й куди піде.

Що надсилається. На кожну нову тривогу — запит POST із тілом тривоги на цю адресу й більше нікуди. Заголовки — Content-Type: application/json; charset=utf-8 і User-Agent: SDR-SA-PRO.
Не більше 8 за огляд. Решта тривог того самого огляду не надсилається, а лічиться пропущеною: пропущено webhook: N (стеля 8 за огляд).
У тлі. Відповідь чекається до 5 с, і огляд «Сканера» на неї не чекає. Успіх — відповідь із кодом 2xx; будь-який інший код — відмова HTTP N; не дочекались — час вичерпано (5 с).
Без переадресацій і повторів. Відповідь 3xx — відмова з її кодом, наприклад HTTP 302: дані не підуть на іншу адресу, ніж ви вписали. Запит, що не вдався, не повторюється.
http:// і https://. http:// іде вашою мережею відкритим текстом; https:// — із перевіркою сертифіката засобами Windows. Інша адреса — відмова адреса webhook має починатись з http:// або https://, порожня — адресу webhook не вказано.

Проба й лічильники

Кнопка Проба тієї самої згортки активна, коли ввімкнено голос, сирену або webhook. З увімкненим webhook вона шле на адресу подію без тривоги — лише три поля: {"event": "test", "program": "SDR-SA-PRO", "time_utc": "…"}.

Що вийшло, каже рядок під вимикачами дій (див. Що з діями вийшло):

webhook — N — скільки запитів дістали відповідь 2xx від запуску програми, разом із пробами; коли щось не вдалось чи пропущено, додано (не вдалось N, пропущено N);
в Останнє — webhook: N у дорозі або webhook — проба в дорозі;
остання відмова — у кінці рядка, наприклад webhook: HTTP 500.

Поки webhook увімкнено, рядок Дії у згортці «Наскільки списку вірити» називає його серед увімкнених дій.

MQTT 0.9.58

Блок MQTT стоїть у згортці Наскільки списку вірити списку Сигнали: N, одразу після блоку «Локальний REST».

Публікувати тривоги: Вмикає з’єднання з брокером. Типово вимкнено. Якщо прапорець стояв перед виходом, програма з’єднується знову, щойно запуститься.
брокер: host, host:port, mqtt://host[:port] — TCP, типово порт 1883, — або mqtts://host[:port] — TLS, типово 8883, сертифікат брокера перевіряє Windows. Адресу зі шляхом, іншою схемою чи портом поза 1…65535 програма не бере: прапорець знімається, а рядок під блоком каже чому.
тема: Корінь тем, типово sdrsa. Порожня тема чи тема з + або # не приймається: тема має бути непорожньою й без символів + та #.
ім'я і пароль: Як їх вимагає брокер; порожньо — без них. Пароль у полі видно крапками.

Кожна зміна поля з’єднує наново.

Що публікується

Кожна нова тривога — у тему <тема>/alarm, тим самим тілом, що й у webhook, з QoS 0, без утримання.
Стан програми — у тему <тема>/status: online одразу після з’єднання й offline перед виходом чи вимкненням прапорця; обидва — утримувані повідомлення. offline стоїть ще й заповітом (Will): коли з’єднання обірветься без попередження, брокер опублікує його сам.
Підписок немає: з брокера програма нічого не читає, крім відповідей самого протоколу, і команд через MQTT не приймає.
Клієнт — власний, MQTT 3.1.1, без сторонніх бібліотек. Ідентифікатор клієнта — sdrsa-pro- і п’ять цифр, сеанс щоразу чистий.

Зв’язок і повтори

З’єднання чекає до 5 с. Не вдалось — нова спроба через 1, 2, 5, 10, 30 с, далі щохвилини.
Брокер відмовив сам — пауза довша: 10 с, далі 30 с, далі щохвилини.
Коли 30 с нічого не надсилалось, клієнт питає брокера, чи той на зв’язку; не дочекався відповіді ще за 30 с — з’єднання вважається втраченим, і за секунду клієнт з’єднується знову.
Поки зв’язку немає, тривоги чекають у черзі — до 500 повідомлень; коли черга повна, найстаріше викидається й лічиться.

Стан каже рядок під блоком: з'єднано з …; надіслано N, у черзі N, викинуто N, з'єднуюсь із mqtt://…, не вдалось з'єднатись: …; наступна спроба через N с, брокер відмовив: …; наступна спроба через N с або з'єднання втрачено: …. Поки прапорця немає, у рядку — коротка підказка про клієнт.

Відмову брокера програма називає словами протоколу:

Код відмови	Що написано
1	брокер не приймає цю версію протоколу
2	брокер відхилив ідентифікатор клієнта
3	служба брокера недоступна
4	неправильне ім'я користувача чи пароль
5	не авторизовано
інший	код відмови N

Ім’я й пароль брокера програма зберігає у файлі settings.json «Сканера» відкритим текстом — так, як ви їх ввели. Хто може прочитати цей файл, прочитає й пароль. Дайте програмі на брокері окреме ім’я з правом лише публікувати у свою тему.

Локальний REST 0.9.58

Блок Локальний REST — у згортці Наскільки списку вірити, перед блоком «MQTT». Прапорець Віддавати стан по HTTP піднімає сервер, поле порт задає порт: від 1024 до 65535, типово 8765. Поруч стоїть адреса, наприклад http://127.0.0.1:8765/.

Лише цей комп’ютер. Сервер слухає тільки 127.0.0.1, і цієї адреси змінити не можна: стан приймача не стане видимим у мережі від одного прапорця. Запити приходять лише від програм на цьому самому комп’ютері.
Лише читання. Сервер відповідає на GET і HEAD; на POST, PUT, DELETE і PATCH — код 405 із заголовком Allow: GET, HEAD. Команд він не приймає, нічого в програмі не змінює й сам нікуди не з’єднується.
Прапорець каже правду. Порт, який уже слухає інша програма, сервер не ділить: прапорець знімається, а рядок під блоком каже не вдалось відкрити порт 8765: …. Число поза межами — порт має бути від 1024 до 65535. Новий порт, поки сервер працює, переносить його туди одразу.
Після запуску програми сервер стоїть. Порт зберігається, а сервер піднімається лише тоді, коли ви поставите прапорець.
Поки сервер працює, рядок під блоком каже працює на http://127.0.0.1:8765/ — запитів: N.

Шляхи

Відповіді — JSON у UTF-8 із заголовком Cache-Control: no-store. Стан оновлюється на кожну його зміну, список і тривоги — після кожного огляду.

Шлях	Що повертає
`/`	Перелік: `program`, `read_only` (`true`), `endpoints` — список шляхів, `events_query` — як питати журнал.
`/state`	Стан «Сканера»: `on` — чи ввімкнено пошук; `state` — рядок стану словами, як на вкладці; `why` — його код (порожньо — працює; `stopped`, `paused`, `tx`, `passport`, `power`, `eof`, `closed`, `failed`); `mode` — `sweep` чи `tuned`; `driver`; `f_lo_hz`, `f_hi_hz`, `df_hz` — межі й крок виміру; `looks` — спектрів у комірці; `rows`, `tentative`, `alarms_unacked`; `method` і `method_used`; `video_search`; `sweep_bands_hz` — смуги свіпу; `events_log` — чи пишеться журнал подій; `time_utc`; `requests` — скільки запитів від запуску програми.
`/list`	`rows` і `count`. Рядок списку: `rowId` — сталий номер рядка; `centerHz`, `widthHz`; `levelDb` (дБ над полицею, `null` — немає), `levelP90Db` (90-й перцентиль рівня влучань), `levelN`; `firstMs`, `lastMs` — час першого й останнього влучання, мілісекунди UTC від 1970 року; `hits`; `state` (1 — є, 2 — зник); `className`, `classKind`; `activity` — ділянка активності; `alarm` (0 — не було, 1 охорона, 2 нагляд, 3 тип, 4 відео) і `alarmNo`; `channel`; `video` (0 — не перевірявся, 1 PAL, 2 NTSC, 3 не відео, 4 синхро без поля, 5 не перевірено).
`/alarms`	`alarms` — останні 200 тривог від запуску програми, від найстарішої, тим самим тілом; `count`; `kept` (200).
`/days`	`days` — доби, за які є файл журналу подій, від найновішої.
`/events?day=РРРР-ММ-ДД`	Журнал подій за добу: `day`, `rows` (до 5000), `total` — рядків у файлі, `skipped` — не прочитаних, `error` — що не вдалося, словами; порожньо — усе гаразд. Без правильної доби — код 400.

Незнаний шлях дістає код 404 і {"error": "unknown path; see /"}.

Межі

Webhook і MQTT кажуть лише про тривоги. Список і стан «Сканера» видно тільки через локальний REST.
Webhook — до 8 запитів на огляд, без повторів: запит, що не дійшов, губиться, і лічильник це каже.
MQTT — лише QoS 0: брокер доставки не підтверджує; поки зв’язку немає, у черзі тримається до 500 повідомлень.
Тіло тривоги не каже, з якої станції вона прийшла.
Локальний REST — лише 127.0.0.1 і лише читання.
Пароль MQTT лежить у settings.json відкритим текстом.
На живому сервері webhook, на живому брокері MQTT і з чужими програмами-клієнтами REST ще не перевіряли; з’єднання mqtts:// не перевірене зовсім.

Wiki описує версію 0.9.58. Версію вашої програми видно в меню «Довідка» → «Про програму». Знайшли неточність? Напишіть нам.