ssvc0059_v2_uart_api_docs

SSVC0059_V2 UART API Версия 1.7

Документация UART API для SSVC0059_V2 Данный документ описывает формат обмена данными по UART с контроллером SSVC0059_V2, включая управляющие команды (запросы) и телеметрию (сообщения).

SSVC0059_V2 UART API — запросы и ответы

Документация к формату запросов и ответов.

Общие правила

Запрос:
- Состоит из заглавных латинских букв, цифр и знака подчеркивания.
- Заканчивается символом \n или \r.
Ответ:
- Передается в формате JSON в одной строке, заканчивающейся символом \n.

Перечень запросов

AT
NEXT
PAUSE
RESUME
STOP
START
STATUS
VERSION
GET_SETTINGS
SET

Общая структура сообщения с ответом

Сообщение с ответом на запрос содержит следующие поля:

type: "response" — тип сообщения.
request: полученная команда в кавычках.
result: "OK" — при успешном выполнении команды, "unknown" — неизвестная команда.

Пример (обобщенный):

{
  "type": "response",
  "request": "AT",
  "result": "OK"
}

Описание запросов

`AT`

Назначение: тест обмена сообщениями.

`NEXT`

Назначение: действие, аналогичное нажатию кнопки «Далее/Выход» на этапах Головы / Тело / Хвосты.

`PAUSE`

Назначение: вход в режим ручного управления клапаном текущего этапа; клапан закрыт.

`RESUME`

Назначение: выход из режима ручного управления клапаном текущего этапа.

`STOP`

Назначение: удаленная остановка процесса на этапах Головы, Тело, Хвосты.

`START`

Назначение: удаленный запуск ректификации, работает только из дежурного режима.

`STATUS`

Назначение: передача статуса от подключенного устройства.
Формат:
- Принимается строка длиной 15 символов.
- Полученное строковое значение отображается на дежурном экране.
Пример:
```
STATUS 192.168.100.200
```

`VERSION`

Назначение: запрос версии прошивки.

Пример ответа:

{
  "type": "response",
  "request": "VERSION",
  "result": "OK",
  "manufacturer": "SmartModule",
  "model": "SSVC0059_V2",
  "version": "2.2.37",
  "api": "1.7"
}

`SET`

Документация по синтаксису команды SET.

Команда SET используется для задания различных настроек. Команда работает во всех режимах, когда контроллер принимает запросы по UART.

Максимальная длина строки — 300 символов, включая завершающие строку \n и нулевой символ.

Общий формат команды

SET <параметр1>=<значение1>,<параметр2>=<значение2>,...,<параметрN>=<значениеN>

Перечень принимаемых параметров

Поддерживается всеми версиями прошивок 2.2.* и 2.3.* (если не указано иное):

heads=[<время_включения>,<период>] — скорость отбора голов.
hearts=[<время_включения>,<период>] — скорость отбора тела.
hyst=<значение> — гистерезис.
decrement=<значение> — декремент.
formula=[0|1] — формула.
tank_mmhg=<значение> — давление в кубе относительно атмосферного (параметр в настройках), мм рт. ст.
tank_mmhg_act=<значение> — актуальное давление в кубе относительно атмосферного (измеряется датчиком), мм рт. ст.
heads_timer=<время> — время отбора голов.
hearts_timer=<время> — таймер фиксации температуры отбора тела.
start_delay=<время> — отложенный пуск.
hearts_finish_temp=<температура> — температура завершения отбора тела.
formula_start_temp=<температура> — начальная температура для формулы.
valve_bw=[<скорость1>,<скорость2>,<скорость3>] — пропускные способности клапанов в мл/ч.
tails=[<значение1>,<значение2>] — скорость отбора хвостов (актуально для firmware 2.2.*).
tails_temp=<температура> — температура завершения отбора хвостов (актуально для firmware 2.2.*).
late_heads=[<время_включения>,<период>] — скорость отбора подголовников (актуально для firmware 2.3.*).
late_heads_timer=<значение> — время отбора подголовников, с (кратно 300 с; актуально для firmware 2.3.*).
parallel=[<время_включения>,<период>] — параллельный отбор клапаном 3 (актуально для firmware 2.3.*).
parallel_v1=[<время_включения>,<период>] — параллельный отбор клапаном 1 (актуально для firmware 2.2.*).
parallel_v3=[[<температура>,<время_включения>,<период>], …] — параллельный отбор клапаном 3 (актуально для firmware 2.2.*).
release_speed=<значение> — скорость сброса (время открытого клапана); актуально с опцией «Сброс и снижение».
release_timer=<время> — время сброса, с; актуально с опцией «Сброс и снижение».
heads_final=<значение> — скорость отбора к окончанию голов; актуально с опцией «Сброс и снижение».

Дополнительно есть оперативные параметры текущего этапа:

s_temp=<температура> — температура, °C (1 знак после запятой, максимум 110.0).
s_hyst=<гистерезис> — гистерезис, °C (2 знака после запятой, от 0.06 до 50.06).
s_speed=[<время_включения>,<период>] — скорость отбора (аналогична heads).
s_decrement=<декремент> — декремент, %, целое число до 100.
s_timer=<время> — таймер, с; целое число до 86400.

Описание параметров

`heads`, `late_heads`, `hearts`, `tails`, `s_speed`, `parallel_v1`, `parallel`

Настройки скорости отбора (время открытого клапана и период цикла).

Назначение:
- heads — головы;
- hearts — тело;
- late_heads — подголовники;
- tails — хвосты;
- s_speed — оперативные параметры;
- parallel_v1 — параллельный отбор клапаном 1 (firmware 2.2.*);
- parallel — параллельный отбор клапаном 3 (firmware 2.3.*).
Синтаксис:
```
heads=[<время_включения>,<период>]
```
- <время_включения> — вещественное число с одной десятичной цифрой (например, 99.0).
- <период> — целое число.
Ограничения:
- время_включения ≤ 99.9
- период ≤ 999
- время_включения ≤ период
Пример:
```
heads=[99.0,100]
```

`hyst`

Описание: устанавливает значение гистерезиса.
Синтаксис:
```
hyst=<значение>
```
- <значение> — число с двумя знаками после запятой (например, 0.25).
Ограничения:
- положительное число, не более 50.0.
Пример:
```
hyst=0.25
```

`decrement`

Описание: устанавливает величину в процентах, на которую будет уменьшаться скорость отбора тела при «злете» температуры.
Синтаксис:
```
decrement=<значение>
```
- <значение> — целое число (например, 20).
Ограничения:
- целое положительное число от 0 до 100 включительно.
Пример:
```
decrement=20
```

`formula`

Описание: использовать или нет формулу для снижения скорости отбора тела в зависимости от температуры на ТД2.
Синтаксис:
```
formula=[0|1]
```
- 0 — не использовать формулу;
- 1 — использовать.
Пример:
```
formula=1
```

`tank_mmhg`

Описание: устанавливает давление в кубе в миллиметрах ртутного столба (мм рт. ст.) относительно атмосферного.
Синтаксис:
```
tank_mmhg=<значение>
```
- <значение> — целое число (например, 30).
Ограничения:
- значение от 0 до 50.
Пример:
```
tank_mmhg=50
```

`tank_mmhg_act`

Назначение: передача актуальных (динамических) показаний датчика давления в систему расчетов.
Если датчик в кубе отсутствует и данные не передаются, контроллер использует статическое значение из tank_mmhg.
Описание: устанавливает давление в кубе в мм рт. ст. относительно атмосферного. Имеет приоритет над tank_mmhg.
Если контроллер получил tank_mmhg_act хотя бы раз, он будет использовать это значение (и игнорировать последующие изменения tank_mmhg) до момента выключения питания.
Синтаксис:
```
tank_mmhg_act=<значение>
```
- <значение> — вещественное число с одной десятичной цифрой (например, 30.0).
Ограничения:
- значение от 0.0 до 50.0.
Пример:
```
tank_mmhg_act=45.5
```

`heads_timer`

Описание: таймер отбора голов (время в секундах).
Синтаксис:
```
heads_timer=<время>
```
- <время> — целое число (например, 36000).
Ограничения:
- положительное число, не более 86400, кратное 300 (5 минут).
Пример:
```
heads_timer=36000
```

`late_heads_timer`

Описание: таймер отбора подголовников (время в секундах).
Синтаксис:
```
late_heads_timer=<время>
```
- <время> — целое число (например, 36000).
Ограничения:
- положительное число, не более 86400, кратное 300.
Пример:
```
late_heads_timer=36000
```

`hearts_timer`

Описание: таймер фиксации температуры отбора тела, мин.
Синтаксис:
```
hearts_timer=<время>
```
- <время> — целое число (например, 10).
Ограничения:
- положительное число, не более 30.
Пример:
```
hearts_timer=30
```

`tails_temp`

Описание: температура завершения отбора хвостов, °C.
Синтаксис:
```
tails_temp=<температура>
```
- <температура> — число с плавающей точкой (например, 109.9).
Ограничения:
- положительное число, не более 110.0.
Пример:
```
tails_temp=109.9
```

`start_delay`

Описание: отложенный пуск (время в секундах).
Синтаксис:
```
start_delay=<время>
```
- <время> — целое число (например, 6000).
Ограничения:
- положительное число, не более 18000.
Пример:
```
start_delay=18000
```

`hearts_finish_temp`

Описание: температура на ТД2, при которой завершается отбор тела, °C.
Синтаксис:
```
hearts_finish_temp=<температура>
```
- <температура> — число с плавающей точкой (например, 93.0).
Ограничения:
- положительное число, не более 110.0.
Пример:
```
hearts_finish_temp=93.0
```

`formula_start_temp`

Описание: начальная температура для начала работы формулы, °C.
Синтаксис:
```
formula_start_temp=<температура>
```
- <температура> — число с плавающей точкой (например, 84.0).
Ограничения:
- температура от 84.0 до 100.0 включительно.
Пример:
```
formula_start_temp=84.0
```

`valve_bw`

Описание: пропускные способности клапанов в мл/ч.
Синтаксис:
```
valve_bw=[<скорость1>,<скорость2>,<скорость3>]
```
- каждая <скоростьN> — целое число.
Ограничения:
- все скорости ≤ 20000.
Пример:
```
valve_bw=[10000,20000,15000]
```

`parallel_v3`

Описание: устанавливает параметры параллельного отбора клапаном 3 на этапе отбора тела (актуально для прошивок 2.2.*).
Задается 4 диапазона, в каждом диапазоне передаются три значения.
Синтаксис:
```
parallel_v3=[[<температура>,<время_включения>,<период>],
             [<температура>,<время_включения>,<период>],
             [<температура>,<время_включения>,<период>],
             [<температура>,<время_включения>,<период>]]
```
- <температура> — начало диапазона, вещественное число с одной десятичной цифрой (например, 84.0).
  (Первый диапазон всегда начинается с 0.0; полученное значение температуры в первом диапазоне игнорируется.)
- <время_включения> — вещественное число с одной десятичной цифрой (например, 99.0).
- <период> — целое число.
Ограничения:
- время_включения < период
- температура ≤ 99.9
- время_включения ≤ 99.9
- период ≤ 999

Пример:

SET parallel_v3=[[0.0,0.4,10],[81.1,0.5,50],[86.2,0.6,50],[96.3,1.1,100]]

`release_speed`

Описание: скорость сброса (время открытого клапана), с; актуально с опцией «Сброс и снижение».
Синтаксис:
```
release_speed=<время_включения>
```
- <время_включения> — вещественное число с одной десятичной цифрой (например, 99.0).
Ограничения:
- время_включения ≤ 99.9.
Примечание: значение должно быть меньше периода этапа отбора голов (контроль возлагается на передающую сторону).
Пример:
```
release_speed=99.0
```

`release_timer`

Описание: время сброса, с. Включается опция «Сброс и снижение» при значении больше 0.
Синтаксис:
```
release_timer=<время>
```
- <время> — целое число (например, 600).
Ограничения:
- положительное число, не более 1200 (20 минут).
Пример:
```
release_timer=600
```

`heads_final`

Описание: скорость отбора к окончанию голов, с. Включается опция «Сброс и снижение» при любом значении.
Синтаксис:
```
heads_final=<время_включения>
```
- <время_включения> — вещественное число с одной десятичной цифрой (например, 10.5).
Ограничения:
- время_включения ≤ 99.9.
Примечание: значение должно быть меньше периода этапа отбора голов (контроль возлагается на передающую сторону).
Пример:
```
heads_final=10.5
```

Проверка на ошибки

При неверном формате или несоответствии ограничениям возвращается сообщение об ошибке.

Пример:
```
{"type": "response","request": "SET heads=[1,2]","result": "error: heads=[1,2]"}
```
Для неизвестных параметров возвращается сообщение об ошибке.

Пример:
```
{"type": "response","request": "ABCD","result": "unknown"}
```

Примеры корректных команд

SET heads=[30.0,180],hearts=[2.5,5],formula=1
SET heads=[60.0,360],hearts=[2.0,4],hyst=0.19,formula=0
SET heads=[20.5,245],hearts=[1.5,3],hyst=0.25,decrement=20,formula=1,tank_mmhg=50,heads_timer=36000,hearts_timer=30,start_delay=18000,hearts_finish_temp=93.0,formula_start_temp=84.0,valve_bw=[10000,11000,12000]
SET formula=1
SET formula=0
SET tank_mmhg=50
SET heads_timer=36000
SET heads_timer=86400
SET hearts_timer=30
SET start_delay=18000
SET hearts_finish_temp=110.0
SET formula_start_temp=84.0
SET formula_start_temp=100.0
SET valve_bw=[10000,11000,12000]

Примеры команд с ошибками

SET heads=[60.0,360],hearts=[2.0,4],hyst=0.19,decrement=30,formula=2
SET heads=[100.0,180],hearts=[2.5,5],formula=1
SET heads=[99.9,1000],hearts=[2.5,5]
SET heads=[99.1,99],hearts=[2.5,5],formula=1
SET hyst=50.01
SET decrement=101
SET tank_mmhg=51
SET heads_timer=86401
SET hearts_timer=31
SET start_delay=18001
SET hearts_finish_temp=110.1
SET formula_start_temp=83.9
SET formula_start_temp=100.1
SET valve_bw=[10000,11000,21000]

`GET_SETTINGS`

Назначение: запрос настроек.
Описание:
- Ответ содержит поле settings — объект с набором параметров.
- Пример JSON-структуры ниже включает все возможные поля, поддерживаемые версиями прошивки 2.2.* и 2.3.*.
- Некоторые поля могут присутствовать только в одной из веток прошивок.

Пример ответа `GET_SETTINGS`

{
  "type": "response",
  "request": "GET_SETTINGS",
  "result": "OK",
  "settings": {
    "heads": [24.5, 100],
    "heads_final": 15.0,
    "release_timer": 300,
    "release_speed": 99.9,
    "late_heads": [23.4, 123],
    "hearts": [2.5, 5],
    "hyst": 0.25,
    "decrement": 100,
    "tails": [2.1, 4],
    "sound": 0,
    "pressure": 1,
    "relay_inverted": 0,
    "relay_autostart": 0,
    "auto_mode": 1,
    "heads_timer": 900,
    "late_heads_timer": 1800,
    "hearts_timer": 0,
    "tails_temp": 95.9,
    "start_delay": 5,
    "hearts_finish_temp": 90.0,
    "parallel_v3": [
      [0.0, 0.4, 10],
      [81.0, 0.5, 11],
      [86.0, 0.6, 12],
      [96.0, 0.7, 13]
    ],
    "parallel_v1": [0.3, 10],
    "parallel": [0.2, 10],
    "hearts_temp_shift": 1,
    "hearts_pause": 1,
    "formula": 1,
    "formula_start_temp": 84.0,
    "tank_mmhg": 10,
    "tp2_shift": 0.0,
    "tp_filter": 0,
    "signal_tp1_control": 1,
    "signal_inverted": 0,
    "tp1_control_temp": 60,
    "tp1_control_start": 1,
    "stab_limit_time": 60,
    "stab_limit_finish": 1,
    "backlight": "active",
    "valve_bw": [1100, 1200, 1300]
  }
}

Структура ответа на GET_SETTINGS

Поля объекта settings

`heads`

Скорость отбора голов.

Время открытого клапана: время в секундах с точностью до 1 знака после десятичной точки.
Период: время в секундах.

`heads_final`

Скорость отбора к окончанию отбора голов, с. Актуально при опции «Сброс и снижение».

Формат: целое число в секундах.

`release_timer`

Время сброса на этапе голов, с. Актуально при опции «Сброс и снижение».

Формат: целое число в секундах.

`release_speed`

Время открытого клапана для сброса, с; задает скорость отбора во время сброса.

Формат: число с одним знаком после десятичной точки.

`hearts`

Скорость отбора тела.

Формат: [время открытого клапана, период]
Время открытого клапана: время в секундах с точностью до 1 знака после десятичной точки.
Период: время в секундах, целое число.

`hyst`

Гистерезис при отборе тела, °C.

`decrement`

Декремент при отборе тела, %.

`late_heads`

Скорость отбора подголовников. Актуально в firmware 2.3.*.

Формат: [время открытого клапана, период]
Время открытого клапана: время в секундах с точностью до 1 знака после десятичной точки.
Период: время в секундах.

`tails`

Скорость отбора хвостов. Актуально в firmware 2.2.*.

Формат: [время открытого клапана, период]
Время открытого клапана: время в секундах с точностью до 1 знака после десятичной точки.
Период: время в секундах.

`sound`

Звук:

1 — включено;
0 — выключено.

`pressure`

Барометр:

1 — включено;
0 — выключено.

`relay_inverted`

Инвертировать реле:

1 — включено;
0 — выключено.

`relay_autostart`

Реле включить сразу:

1 — включено;
0 — выключено.

`auto_mode`

Автоматический переход между этапами:

1 — включено;
0 — выключено.

`heads_timer`

Время отбора голов, с.

`late_heads_timer`

Время отбора подголовников, с. Актуально в firmware 2.3.*

`hearts_timer`

Таймер фиксации температуры отбора тела, с.

`tails_temp`

Температура завершения отбора хвостов, °C. Актуально в firmware 2.2.*

`start_delay`

Отложенный пуск, с.

`hearts_finish_temp`

Температура ТД2 завершения отбора тела, °C.

`parallel_v3`

Скорость параллельного отбора клапаном №3 для 4 диапазонов. Актуально в firmware 2.2.*.

Формат: [[температура диапазона, время открытого клапана, период], ...]
Температура диапазона: температура в °C.
Время открытого клапана: время в секундах с точностью до 1 знака после десятичной точки.
Период: время в секундах.

`parallel_v1`

Скорость параллельного отбора клапаном №1. Актуально в firmware 2.2.*.

Формат: [время открытого клапана, период]
Время открытого клапана: время в секундах с точностью до 1 знака после десятичной точки.
Период: время в секундах.

`parallel`

Скорость параллельного отбора клапаном №3 (актуально в firmware 2.3.*).

Формат: [время открытого клапана, период]
Время открытого клапана: время в секундах с точностью до 1 знака после десятичной точки.
Период: время в секундах.

`hearts_temp_shift`

Сдвиг температуры отбора тела на 0.07 °C:

1 — включено;
0 — выключено.

`hearts_pause`

Пауза «на себя»:

1 — включено;
0 — выключено.

`formula`

Формула:

1 — включено;
0 — выключено.

`formula_start_temp`

Температура начала формулы, °C.

`tank_mmhg`

Давление в кубе, мм рт. ст.

`tp2_shift`

Поправка ТД2, °C.

`tp_filter`

Фильтр ТД:

1 — включено;
0 — выключено.

`signal_tp1_control`

Контроль ТД1 для выхода SIGNAL:

1 — включено;
0 — выключено.

`signal_inverted`

Инвертировать SIGNAL:

1 — включено;
0 — выключено.

`tp1_control_temp`

Целевая температура на ТД1 при контроле ТД1 для выхода SIGNAL, °C.

`tp1_control_start`

Старт по ТД1 при контроле ТД1 для выхода SIGNAL:

1 — включено;
0 — выключено.

`stab_limit_time`

Лимит стабилизации, с (0 — отключен).

`stab_limit_finish`

Завершить этап при превышении лимита стабилизации:

1 — включено;
0 — выключено.

`backlight`

Подсветка дисплея.

Возможные значения:
- "active" — включено;
- "always" — всегда включено;
- "off" — выключено.

`valve_bw`

Пропускная способность клапанов.

Формат: [клапан 1, клапан 2, клапан 3]
Значения: пропускная способность в мл/ч соответствующего клапана.

Cтруктура телеметрии (JSON)

Формат сообщения телеметрии

Общая структура сообщения

Сообщения передаются в формате JSON в одной строке, заканчивающейся символом \n.
Каждое сообщение содержит поле type, определяющее тип сообщения.
Дополнительные поля зависят от значения type.

Типы сообщений и их поля

Дежурный режим — `type: "waiting"`

Сообщение состоит из общей для всех сообщений части common.

Общая часть `common`

Сообщение содержит следующие поля:

mmhg: float — давление в мм рт. ст.
tp1: float — температура ТД1.
tp2: float — температура ТД2.
relay: int — состояние реле (0 или 1).
signal: int — состояние сигнала (0 или 1).
cfg_chgd: boolean — флаг для запроса настроек GET_SETTINGS. Присутствует только если true.
Флаг необходим для запроса настроек в случае, если были внесены изменения на контроллере при помощи кнопок управления. Сбрасывается после запроса GET_SETTINGS.
tts: int — время до сохранения настроек в энергонезависимую память, с. При отсутствии поля tts — несохраненных данных нет.

Пример `waiting`

{
  "type": "waiting",
  "common": {
    "mmhg": 750.5,
    "tp1": 30.31,
    "tp2": 30.81,
    "relay": 1,
    "signal": 0,
    "cfg_chgd": true
  }
}

Экраны настроек ректификации — `type: "settings"`

Сообщение также состоит из общей части common (структура аналогична описанной выше).
Дополнительные поля зависят от конкретной реализации экранов и не детализированы в данном документе.