Выражения Formulas
Синтаксис выражений, типы входов, тестовые запросы поставщику и применение расчёта в модели.
Выражение, входы и привязки
Пользователь вводит выражение в «УСЕПИ» → «Формулы», задаёт типы и применяет сохранённую формулу в устройстве. Formulas не импортирует карту Bridge и не читает MQTT напрямую. Пути источников и константы назначаются входам устройства, а не в настройках экземпляра или тексте выражения.
Примеры ниже используют синтетические значения. TXT служит памяткой для редактора; JSON содержит тестовые запросы разработчика к поставщику. Это не экспорт устройства, не конфигурация экземпляра и не файл для кнопки импорта.
Синтаксис и типы
Результат только number или boolean. Массив, объект и null не являются допустимым входом одного из этих типов. Циклы, присваивания, цепочки выражений и неизвестные функции отклоняются; код JavaScript не исполняется.
Вычисления используют IEEE-754 binary64: большие целые за пределами 2^53 могут терять точность. Формула не хранит единицы измерения и не переводит их автоматически; согласуйте масштаб и единицы входов отдельно.
| Элемент | Правило |
|---|---|
| Имя переменной | [A-Za-z_][A-Za-z0-9_]{0,63}; регистр важен. Имена берутся из выражения; объявите точный тип каждого входа. |
| number | Конечное JSON-число; дробная часть с точкой. Число в кавычках — text, а не number. |
| text | Строка; в выражении строковый литерал заключается в двойные кавычки, например Status == "run". Текст допустим как вход, но не как результат. |
| boolean | Логическое true или false, не строки. &&, || и ! применяются к boolean. |
| Арифметика | +, -, *, /, %, ^ для чисел. Скобками задавайте нужный порядок; 5 / 2 возвращает 2.5. |
| Сравнения | == и != для значений одного типа; >, >=, < и <= для чисел. Результат сравнения — boolean. |
| Числовые функции | min(A, B), max(A, B), floor(A), ceil(A), round(A), abs(A). |
| if(condition, yes, no) | Условие boolean; обе ветви одного типа и обе проходят проверку. Не используйте выбор ветви как обещание безопасного деления или пропуска проверки. |
Запрос одного вычисления
Это payload операции formula.evaluate.v1 через контролируемый канал вызова поставщика Plugin Manager. Он не публикуется в MQTT и не отправляется на придуманный публичный HTTP endpoint. Вызовы выполняйте в согласованном изолированном тестовом Host с разрешениями; документация не предоставляет доступ к чужим моделям.
Для приведённых входов ответ одного вычисления — {"value":15}. formula.validate.v1 проверяет выражение и типы, но не вычисляет тестовые входы и не сохраняет пользовательскую формулу.
{
"expression": "(A + B) / 2",
"inputTypes": {"A": "number", "B": "number"},
"inputs": {"A": 10, "B": 20},
"outputType": "number"
}| Поле | Назначение |
|---|---|
| expression | Непустое выражение, до 4096 байт UTF-8. |
| inputTypes | Объект имя → number, text или boolean; от 0 до 128 входов. Для константного выражения используйте {}. |
| inputs | Объект имя → фактическое значение. Для вычисления набор имён обязан точно совпасть с inputTypes, без пропущенных или лишних значений. |
| outputType | Обязательный number или boolean, соответствующий выражению. |
Скачиваемые тесты и пакетный расчёт
JSON-пример содержит пять запросов в requests для formula.evaluate.batch.v1: среднее, масштаб, логическое условие, выбор по тексту и константу. Ожидаемый ответ приведён ниже; порядок values совпадает с порядком requests. Для одиночного вызова используйте один объект из массива, без внешней обёртки requests.
Пакет допускает от 1 до 256 запросов. Ошибка любого выражения отклоняет весь вызов; частичный массив результатов не является успешным ответом. Проверка этих примеров не подтверждает наличие источников и обновление модели в конкретной установке.
{"values":[15,12.5,true,42,2.5]}Ограничения и диагностика
Кроме размера выражения и числа входов, действуют score не больше 160 и глубина скобок не больше 16. Конечный результат ограничен 256 КиБ. Редактор показывает сложность и доступный запас после проверки; не оценивайте допустимость только по длине строки.
Нельзя исправлять отсутствующий вход случайным нулём или числовую строку неявным преобразованием. Устраните источник или тип. При ошибке расчёта активной модели предыдущий согласованный снимок сохраняется: оставшееся значение не доказывает успех нового вычисления.
| Код | Что исправить |
|---|---|
| FORMULA_EXPRESSION_INVALID | Синтаксис, пустое или слишком длинное выражение. |
| FORMULA_INPUTS_INCOMPLETE | Пропущенные или лишние фактические входы относительно inputTypes. |
| FORMULA_INPUT_TYPE_MISMATCH | Тип фактического значения: number, text или boolean. |
| FORMULA_OUTPUT_TYPE_INVALID / FORMULA_OUTPUT_TYPE_MISMATCH | Тип результата, несогласованные ветви или неконечный числовой результат, например при делении на ноль. |
| FORMULA_FUNCTION_FORBIDDEN / FORMULA_ASSIGNMENT_FORBIDDEN | Недопустимая функция или присваивание; перепишите выражение разрешёнными операторами. |
Применение в устройстве
- Проверьте работающий экземпляр и разрешения Formulas. Создайте выражение в редакторе, назначьте типы, выполните «Проверить» и дождитесь успешного сохранения.
- В устройстве выберите формульное поле, назначьте сохранённую формулу и заполните все входы константами либо USEPI-источниками соответствующего типа.
- Проверьте сохранение, отдельно включите трансляцию и сравните начальный результат с известными значениями. Измените один вход и проверьте полный обновлённый снимок модели.
- После правки общей формулы примените нужную ревизию к устройству явно: оно хранит собственный снимок выражения, типов, привязок и точного поставщика. Установка другой версии плагина не выполняет эту миграцию автоматически.