atomspectra-waterfall-esp32

Протокол Atom Spectra — команды и формат пакетов

🇷🇺 Русская версия · 🇬🇧 English

Справочник по протоколу обмена с многоканальным анализатором (MCA) серии Atom Spectra PRO / Atom Nano 8: текстовые команды управления/настройки и бинарный пакетный протокол shproto, по которому работает этот шлюз.

Анализатор общается через виртуальный COM-порт (USB, FTDI). Параметры порта: 8 N 1, скорость одна из 38400 | 115200 | 460800 | 600000 | 921600. На 38400 и 115200 выгрузить весь спектр за 1 секунду невозможно. Все текстовые команды завершаются Enter.

⚠️ Команды настройки (Settings and fine tuning) меняют заводскую конфигурацию прибора. Используйте их с осторожностью — шлюзу для обычной работы они не нужны.

Что использует этот шлюз

Действие шлюза Команда / код
Запрос параметров и калибровки при подключении текстовая -inf
Кнопка «Сброс» в Web UI текстовая -rst
Произвольная команда из Web UI (/api/command) любая текстовая (напр. -sta, -sto, -sho)
Приём гистограммы пакет cmd 0x01
Приём статуса (CPS, dead-time…) пакет cmd 0x04
Приём текстовых ответов пакет cmd 0x03

Режимы работы

Команда Описание
-mode 0\|1\|2 Переключение режима: 0 — MCA (нормальная работа), 1 — осциллограф, 2 — просмотр импульсов. Режимы 1/2 — для заводской настройки аналоговой части.

MCA — управление набором спектра

Команда Описание
-sta [xx] [-r] [-s] Старт набора. xx — время набора в секундах; -r — сброс спектра перед стартом; -s — silent (прибор НЕ выгружает спектр каждую секунду).
-sto Остановить набор.
-sho Выгрузить текущий спектр.
-stt Выгрузить текущий статус MCA (collecting — идёт обработка, stopped — нет).
-rst Сбросить текущий спектр.

Режим просмотра импульсов

Команда Описание
-dbg XXX YYY Диапазон бинов для выгрузки осциллограмм импульсов (XXX — нижний бин, YYY — верхний). Пример: -dbg 600 700.

Настройка обработки импульсов (заводская)

Команда Описание
-ris XX Число точек АЦП на фронт импульса (rise).
-fall YY Число точек АЦП на спад импульса (fall).
-max ZZ Максимальное значение интеграла. При достижении — импульс инкрементирует последний бин 8191.
-U[0-255] Регулировка высокого напряжения (HV).
-V[0-255] Регулировка базовой линии (baseline).
-nos AA Уровень дискриминатора.
-hyst BB Гистерезис дискриминатора (рекомендуется 1).
-frq CCCCCCC Частота дискретизации АЦП в Гц (макс. 21 МГц). Если значение недоступно — установится ближайшее большее доступное.
-step D Шаг сравнения дискриминатора. На высоких частотах АЦП должен быть >1, чтобы не перегружать CPU.

Температурная компенсация (макс. интеграл)

Команда Описание
-tclear Очистить данные температурной компенсации макс. интеграла.
-t M N O Добавить точку: M — номер (1..20), N — температура, O — макс. интеграл для неё. До 20 точек, между точками — линейная интерполяция.
-tp EEEE Время между пересчётами макс. интеграла, мс (рекомендуется 1000).
-tc on\|off Включить/выключить температурную компенсацию макс. интеграла.

Температурная компенсация базовой линии

Команда Описание
-tc_pot? Запрос параметров температурной компенсации baseline.
-tc_pot on Включить компенсацию baseline.
-tc_pot off Выключить компенсацию baseline.
-t_pot H K L Добавить точку компенсации baseline (H — номер 1..20, K — температура, L — значение).

Режекция наложений импульсов (pile-up / overlapping)

Команда Описание
-pileup [v1 v2 … v100] Значения компенсации pile-up (для детекторов с послесвечением, напр. CsI(Tl)). Каждое 0..1.
-pthr [value] Минимальная амплитуда импульса для активации pile-up компенсации. 8192 — выключить.
-prise [value1] Уровень АЦП (в % от амплитуды) за N отсчётов ДО пика.
-srise N Число отсчётов до пика (0 — фильтр выключен).
-pfall [value2] Уровень АЦП (в % от амплитуды) через M отсчётов ПОСЛЕ пика.
-sfall M Число отсчётов после пика (0 — фильтр выключен).

Логика: если значение АЦП выше value1% от пика за N отсчётов до пика или выше value2% через M отсчётов после пика — импульс считается наложенным и отбрасывается.

Регистры, калибровка и серийный номер

Команда Описание
-cal [0-39] hhhhhhhh 40 регистров по 4-байтному числу каждый. Без аргументов — вернуть все данные. С адресом регистра и данными — записать. Первые 12 регистров — данные калибровки, последний регистр (39) — серийный номер.

Прочие команды

Команда Описание
-inf Запрос параметров настройки (см. пример ответа ниже).
-spd 38400\|115200\|460800\|600000\|921600 Скорость COM-порта. Использовать с особой осторожностью!
-sel 1\|2 1\|0 Управление выходными пинами CPU (зарезервировано).
-win EEE FFF Энергетическое окно для режима поиска (зарезервировано).
-div G Делитель импульсов в режиме поиска (зарезервировано).
-defaults_save Сохранить копию всех настроек.
-defaults_restore Восстановить настройки из копии.
-reboot Перезагрузка прибора.

Пример ответа на -inf

VERSION 13 RISE 8 FALL 12 NOISE 15 F 3000000.00 MAX 30000 HYST 1 MODE 0 STEP 1 t 9219
POT 102 POT2 26 T1 OFF T2 OFF T3 33.5 OUT 0..0/1 Prise 0 Srise 0 Pfall 0 Sfall 0
TC OFF TCpot OFF Tco [0 0 … 0] TP 1000 PileUp [] PileUpThr 8192
Поле Значение
VERSION 13 Версия прошивки
RISE 8 FALL 12 Фронт/спад импульса в отсчётах АЦП (для интегрирования)
NOISE 15 Уровень шумового дискриминатора
F 3000000.00 Частота дискретизации АЦП
MAX 30000 Максимальное значение интеграла
HYST 1 Гистерезис дискриминатора
MODE 0 Текущий режим работы
STEP 1 Шаг сравнения дискриминатора
t 9219 Секунд набора текущего спектра
POT 102 POT2 26 Значения U и V соответственно
T1/T2/T3 Датчики температуры (OFF — не подключён; 33.5 — °C)
Prise/Srise/Pfall/Sfall Параметры режекции наложений
TC / TCpot Статусы температурных компенсаций
TP 1000 Период пересчёта макс. интеграла, мс
PileUp / PileUpThr Данные и порог pile-up компенсации

Бинарный протокол shproto — уровень пакета

Обмен идёт по виртуальному COM-порту, 8 N 1, бинарный протокол shproto.

Структура пакета:

0xFF 0xFE   <cmd>   <payload…>   <CRC16 lo> <CRC16 hi>   0xA5
└── start ──┘                    └── CRC16 Modbus ────┘  └ finish

Эталонная реализация парсера (shproto.c / shproto.h) входит в документацию производителя. В этом проекте — components/shproto/.

Коды команд (пакетный уровень)

Код Назначение
0x01 Гистограмма (спектр)
0x02 Осциллограф (4096 точек АЦП)
0x03 Текст (текстовые команды и ответы, напр. -inf)
0x04 Статус/доп. информация

Пакет гистограммы (cmd 0x01)

if (packet.cmd == 0x01) {                 // гистограмма
    uint16_t offset = *(uint16_t*)&packet.data[0];
    if (offset == 0) hist_width = 0;
    uint8_t *p = &packet.data[2];
    int count = (packet.len - 2) / 4;
    for (int i = 0; i < count; i++) {
        int idx = offset + i;
        if (idx < HISTOGRAM_SIZE)
            hist[idx] = p[i*4] | (p[i*4+1]<<8) | (p[i*4+2]<<16) | (p[i*4+3]<<24);
    }
}

Пакет статуса (cmd 0x04)

Последовательно (little-endian):

Поле Тип Описание
time long (u32) Секунд набора текущего спектра
cpu_load short (u16) Загрузка CPU, %
cps long (u32) Импульсов в секунду
dead_time (invalid_pulses) long (u32) Счётчик отбракованных импульсов (offset 10). Эталон BecqMoni использует как InvalidPulses: TotalPulseCount = ValidPulseCount + InvalidPulses
pulse_width long (u32) Суммарная ширина импульсов (отсчёты АЦП, offset 14). В расчёте мёртвого времени не участвует (диагностика)

Мёртвое/живое время (#DT-4). Метод эталонного ПО BecqMoni (Am6er, Utils/LiveTime.cs + AtomSpectraVCPDeviceForm.cs): мёртвое время на импульс τ = (RISE+FALL+1) / F, где RISE/FALL/F берутся из ответа -inf (т.е. сообщаются прибором). Мёртвое время за набор: dead = (ValidPulseCount + InvalidPulses) · τ, live_time = time − dead, где ValidPulseCount — сумма гистограммы, InvalidPulses — поле offset 10. Поле pulse_width (offset 14) эталоном не используется и в расчёт не идёт.

Источники

Этот файл — собственное описание, составленное на основе перечисленных источников. Числовые форматы и коды команд сверены с реализацией протокола в components/shproto/ и main/ этого репозитория.

This site is open source. Improve this page.