Зеленый роботДанные и программные интерфейсы
- Документ
- D08 · АСУП.466459.100-01 33 01
- Редакция
- 2.0 · Проектная редакция
- Применимость
- Функциональный профиль GR-FP-1.0
- Продукт
- Модульное интегрированное ПО «Зеленый робот»
Обозначения и сокращения раскрыты в словаре этой книги.
1. Назначение справочника интерфейсов
Книга определяет данные и взаимодействия X01–X14 функционального профиля GR-FP-1.0. Участник обмена проверяет схему, идентичность, полномочия, исходную редакцию и срок до применения изменения. Машиночитаемая схема поставки и её digest указываются в D13.
Имена существующих API воспроизводятся в разделах соответствующих компонентов. X13/X14 задают проектные программные контракты обслуживания и испытаний GR-FP-1.0. Привязка операции к каналу и адресу входит в профиль интерфейса поставки; смысл данных сохраняется для графического и командного клиента.
Рисунок D08.1 — Идентификаторы связывают запрос, решение, доставку, исполнение и наблюдение.
2. Общие правила данных
| Свойство | Представление | Проверка получателя |
|---|---|---|
| Схема | Имя и версия | Поддерживаемая редакция |
| Идентификатор | Непустая строка из пространства владельца | Уникальность в установленной области |
| Время | RFC 3339, UTC в обмене | Синтаксис, порядок и допустимый возраст |
| Длительность | Целое с единицей в имени поля | Диапазон и конечный срок |
| Измерение | Значение, единица, время, качество | Тип, масштаб и применимость |
| Редакция | Идентификатор и digest | Совпадение исходной базы |
| SHA-256 | 64 шестнадцатеричных символа | Сверка с определёнными bytes |
| Ссылка на секрет | Идентификатор защищённого материала | Доступ в целевой области |
| Ошибка | Код, причина, путь поля/шаг и correlation ID | Предусмотренное восстановление |
Размеры, количество элементов и сроки ограничиваются схемой и профилем. Получатель отклоняет неизвестную версию или поле, когда схема требует строгого набора. Численные технологические параметры имеют явную единицу. Для целочисленных расчётных контрактов применяются указанные правила округления и контроля переполнения.
3. X01 — Идентичность объекта и узла
D08-X01. X01 · Идентичность и роль — последовательность и наблюдаемый результат.
Области идентичности: площадка, технологический объект, программный узел, endpoint, роль и экземпляр компонента. Регистрация endpoint связывает техническую идентичность с разрешённой ролью. Прикладная готовность подтверждается отдельной проверкой обмена и readback.
| Данные | Владелец | Жизненный цикл |
|---|---|---|
| Площадка и объект | Прикладной владелец L2 | Создание, изменение реквизитов, архивирование |
Endpoint и доверие | Процесс присоединения | Подготовка, подтверждение, выдача, отзыв |
| Роль устройства | Конфигурация объекта | Назначение, замена, восстановление |
| Программный экземпляр | Исполнитель компонента | Запуск, наблюдение, завершение |
При замене панели наладчик выбирает существующий объект и роль, присоединяет новую идентичность и получает согласованный snapshot. После установки проверяются выполняемая версия, конфигурация, связь и доступное действие. Конфликт привязки требует чтения действующего назначения и нового подтверждённого изменения.
4. X02 — Сигналы и CANopen
D08-X02. X02 · Сигнал и CANopen — последовательность и наблюдаемый результат.
Карта сигнала связывает физическую величину с программным объектом: ID, index/subindex, тип, единица, масштаб, доступ, период и качество. Словарь объектов поставляется с версией и связью с образом M02. Изменение словаря сопровождается проверкой потребителей и миграцией конфигурации.
| Механизм | Предмет | Подтверждение |
|---|---|---|
| SDO read/write | Сервисное значение словаря | Ответ с типом/длиной либо abort code |
| PDO | Циклические значения | Получение по согласованному mapping и периоду |
| Heartbeat | Присутствие и состояние NMT | Актуальная временная отметка |
| NMT | Состояние узла | Наблюдаемое состояние после команды |
| EMCY | Аварийный факт | Код и данные события |
Перед записью проверьте состояние узла, тип, диапазон и полномочия. После успешной записи прочитайте применённое значение и наблюдаемый сигнал. При ошибке сопоставьте index/subindex и abort code. Узел сохраняет определённое локальным профилем поведение при потере heartbeat или верхнего уровня.
4.1. Версии компонентов платы
AT32 и ESP32 получают отдельные записи: тип компонента, выполняемая версия, источник чтения, время, присутствие и доступность. Метаданные устанавливаемого пакета хранятся отдельно. USB предоставляет отдельные типизированные чтения каждого MCU; WEB/MQTT сохраняют ту же семантику. Аппаратная ревизия и программная версия имеют собственные поля. Пример применения — D05, проверка — D16.
5. X03 — Телеметрия и журнал
D08-X03. X03 · Телеметрия и история — последовательность и наблюдаемый результат.
Конверт события содержит версию схемы, event ID, источник, эпоху/последовательность, время источника и приёма, объект, тип, качество и payload. Прикладной владелец определяет порядок своего потока. Потребитель сохраняет курсор последней принятой позиции.
После разрыва получатель запрашивает диапазон от курсора. Источник выдаёт ограниченные части с идентификаторами, границами и подтверждением целостности. Получатель проверяет части, сохраняет факты и подтверждает принятый диапазон. Повтор части сопоставляется с исходными ID.
| Ситуация | Правило |
|---|---|
| Позднее событие | Сохраняется время источника и время получения |
| Повтор ID | Применяется установленная идемпотентность |
| Разрыв последовательности | Запрашивается доступный диапазон или новый снимок |
| Истечение хранения | Возвращаются границы доступной истории и причина |
| Заполнение очереди | Применяется явная политика приоритета/сохранения профиля |
| Устаревшее измерение | Качество меняется по допустимому возрасту |
Экранная пагинация использует устойчивые ID и курсоры. Бюджет DOM, кеша и live-буфера конечен. Ручное чтение сохраняет строку и смещение; переход к текущему потоку выполняется отдельным действием.
6. X04 — Команды и квитанции
D08-X04. X04 · Команда и квитанции — последовательность и наблюдаемый результат.
Запрос содержит command ID, объект, действие, параметры, исходную редакцию, срок и контекст полномочий. Владелец проверяет его до отправки исполнителю. Содержимое запроса с одним ID имеет определённый digest; повтор с другим содержимым возвращает конфликт.
| Квитанция | Производитель | Значение |
|---|---|---|
| Регистрация запроса | Прикладной владелец | Запрос принят в устойчивый процесс |
| Допуск | Владелец действия с проверкой Auth | Выполнены полномочия и условия |
| Доставка | Транспорт | Выполнен транспортный этап |
| Исполнение | Целевой компонент | Действие выполнено либо получен прикладной отказ |
| Наблюдение | Источник readback | Зафиксировано состояние после действия |
Каждая запись содержит ID операции, этап, результат, время и код причины. Истечение срока завершается установленным результатом; поздняя квитанция сохраняет фактическое время и связывается с исходной командой. После restart владелец восстанавливает устойчивое состояние и проверяет фактический результат перед повторным воздействием.
7. X05 — Конфигурация и паспорт
D08-X05. X05 · Конфигурация и паспорт — последовательность и наблюдаемый результат.
Владелец конфигурации хранит активную редакцию, её digest и историю переходов. Предложение содержит base_revision; применение проходит validate → stage → apply → readback → commit. Конфликт базы возвращает фактическую редакцию для подготовки нового предложения.
| Структура | Содержимое | Пример |
|---|---|---|
| Паспорт | Постоянные параметры и сведения ввода | Геометрия и расход машины |
| Оперативный сценарий | Задание пользователя | Сектор и норма полива |
| Наблюдение | Фактические измерения | Угол, давление, качество |
| Результат расчёта | Вычисленные значения и происхождение | Таймер, время и глубина |
Расчётный результат Pivot связывает passportHash, profileRevision, profileHash, vectorSetHash, scenarioRevision и resultHash. Участники используют согласованные целочисленные единицы и правила округления. Для расчётно-зависимого действия проверяется совпадение digest предусмотренных профилем участников.
8. X06 — MQTT и межсервисный обмен
D08-X06. X06 · Обмен площадки — последовательность и наблюдаемый результат.
Профиль транспорта определяет principal, пространство тем, направление, QoS, retained, срок сообщения и сессии. Клиент и сервис проверяют взаимное доверие, время и доступ площадки. Служебный участник использует отдельную идентичность.
| Категория сообщения | Направление | Правило применения |
|---|---|---|
| Наблюдение | Источник → прикладной владелец | Время, качество, последовательность |
| Команда | Владелец → исполнитель | ID, срок, область и параметры |
| Квитанция | Участник этапа → владелец | Этап, результат и correlation ID |
| Конфигурация | Владелец → роль объекта | Редакция, digest и исходная база |
| Присоединение | Endpoint ↔ enrollment service | Ограниченная операция идентичности |
Точная таблица topic задаётся транспортной схемой выпуска. Производитель проверяет допустимый размер и срок; потребитель обрабатывает повторы и ограничивает очередь. При backpressure профиль определяет замедление, накопление и результат превышения лимита. Смена сети или брокера сохраняет отдельный доступ обслуживания на время проверки нового канала.
9. X07 — Приложение и хост
D08-X07. X07 · Приложение и хост — последовательность и наблюдаемый результат.
Манифест ioot.l1-app-manifest/1.0 связывает app ID, версию, source, frontend digest, маршруты, API-префиксы, регистрацию, health, совместимость и capabilities. Композиция ioot.l1-app-composition/1.0 задаёт проверенный набор манифестов и артефактов. Регистрация 2.0 описывает страницы, настройки, события, уведомления, действия и схемы данных.
При открытии хост определяет контекст, проверяет доступ, выдаёт frontend и API-сессию. Приложение получает snapshot и подписывается на события. После смены объекта выполняется согласованная смена контекста и новое чтение. После reload подписка восстанавливается от актуального snapshot.
9.1. Прикладные API
| Компонент | Чтение | Изменение/события |
|---|---|---|
| Runtime | /api/v1/platform/apps, /api/v1/hmi, /livez, /readyz | Композиция, operator-access и предусмотренный rollback |
| Visio | /api/v1/apps/app-visio в пространстве API владельца | SSE /api/v1/apps/app-visio/events |
| Весовая | /weight/api/v1/runtime/state | /runtime/events?after_seq=N, /runtime/actions в том же префиксе |
| ScaleProxy | /api/weight, /api/state, /api/status, /ready | Ограниченный /api/events с cursor |
Для весовой действие содержит expected_seq; при конфликте клиент получает актуальный snapshot. Для Visio схема snapshot v2 различает IMAGE_SURVEY и TEXT_RESPONSE, состояния обработки и происхождение результата. Для ScaleProxy масса возвращается в тоннах с признаком свежести.
10. X08 — Пользователь и разрешение
D08-X08. X08 · Разрешение операции — последовательность и наблюдаемый результат.
Процесс входа связывает identity, фактор, challenge и сессию. Принимающий сервис проверяет действие в области объекта по действующей политике. Решение содержит ID, субъект, область, функцию, результат и время. Профиль определяет приоритет правил и срок применимости решения.
Отзыв сессии влияет на последующие обращения согласно политике. При ошибке сессии API возвращает 401; конфликт редакции — 409; временная недоступность зависимости — предусмотренный 503. Клиент сохраняет контекст исходной операции и выполняет повтор после восстановления доступа.
Административный и технологический доступ имеют отдельные действия. Контекст сессии передаётся защищённым способом; журналы содержат безопасные идентификаторы решения. Контрольный сценарий проверяет просмотр, разрешённое действие, отказ другого объекта и отзыв.
11. X09 — Уведомления
D08-X09. X09 · Событие и уведомление — последовательность и наблюдаемый результат.
Запрос доставки связывает event ID, объект, получателя, тип, приоритет, срок, текст и допустимые вложения. Ключ повторения определяется исходным событием и назначением доставки. Канал возвращает квитанцию с попыткой, временем и результатом.
При временной ошибке применяется политика повторов в пределах TTL. При окончательном отказе сохраняется причина и маршрут. Интерактивный ответ пользователя проходит самостоятельную проверку полномочий и допуска действия. Исходный факт, доставка, ознакомление и технологическое воздействие имеют собственные подтверждения.
12. X10 — Производные данные и аналитика
D08-X10. X10 · Производные данные — последовательность и наблюдаемый результат.
Запрос выборки содержит область объекта, период, тип записи, фильтры и ограничение объёма. Ответ содержит элементы, курсор, время обновления и происхождение. Производная запись связывает source ID, digest и версию преобразования. При перестроении индекса фиксируются исходный диапазон и результат проверки.
Аналитическое задание содержит профиль, входную схему, разрешённые источники, исполнителя, лимиты и выходную схему. Результат связывает каждый вывод с исходными записями и их hash. Исполнитель возвращает фактически использованные артефакты модели/алгоритма и конечное состояние.
Права выборки распространяются на результат и экспорт. При нарушении входной схемы или ресурса возвращается типизированная ошибка. Повторяемое испытание использует фиксированный набор, профиль и критерии результата; стохастический профиль дополнительно фиксирует seed и правила оценки.
13. X11 — Артефакты и обновление
D08-X11. X11 · Программное обновление — последовательность и наблюдаемый результат.
| Поле manifest | Тип | Назначение |
|---|---|---|
| Artifact ID/type | Строки | Компонент и программная форма |
| Версия/исходная ревизия | Версия и commit | Идентичность выпуска |
| Target | Профиль ОС/архитектуры или MCU | Совместимость исполнения |
| Size/SHA-256 | Целое байт / digest | Целостность |
| Signature reference | Ссылка и алгоритм профиля | Проверка происхождения |
| Dependencies | Версии, схемы и артефакты | Граф совместимости |
| Migration/recovery | Процедуры и исходные версии | Допустимый переход |
| License/SBOM | Ссылки и digest | Условия и состав зависимостей |
Переход: доставка → проверка → staging → применение → restart → readback → фиксация результата. Загрузчик, ядро, PLC-программа, ESP32 firmware и конфигурация имеют отдельные идентичности. Образ применяется к совпадающей цели. При повреждении или несовместимости план завершается адресной ошибкой до активации.
14. X12 — Хранение и восстановление
D08-X12. X12 · Хранение и возврат — последовательность и наблюдаемый результат.
| Данные | Владелец | Единица копии/экспорта |
|---|---|---|
| Конфигурация/паспорт | Владелец объекта | Редакция, schema, digest |
| Оперативный журнал/команды | M11 и локальный владелец | Согласованный диапазон и курсор |
| Взвешивание | M19 | Запись, происхождение и связанная история |
| Производный индекс | M15 | Версия преобразования и исходный диапазон |
| Идентичности/политики | M12 | Совместимый защищённый снимок |
| Пакеты/модели | Владелец артефакта | Неизменяемые bytes и manifest |
| Задания/прогоны | M17/M18 | Устойчивое состояние и доказательства |
Профиль задаёт место, срок, объём, RPO/RTO и доступ. Восстановление проверяет совместимость схем, полноту копии и контрольные записи. Экспорт содержит период, единицы и происхождение. Завершение использования включает передачу нужных данных и установленное действие над каждым типом по D14.
15. X13 — Сервисные задания
D08-X13. X13 · Сервисное задание — последовательность и наблюдаемый результат.
Контракт green-robot.service-job/1.0 определяет операции plan.create, plan.validate, job.start, job.get, job.events, job.cancel, job.resume, job.rollback. Клиент передаёт типизированный запрос; профиль сервиса публикует его транспортную привязку и схему ответа.
15.1. Основные поля
| Поле | Тип | Правило |
|---|---|---|
schema | Строка | green-robot.service-job/1.0 |
requestId | Строка | Ключ повторения обращения |
operation | Перечисление | Одна из операций X13 |
scopeId | Строка | Площадка/объект в области доступа |
profileId, profileRevision | Строки | Выбранный программный профиль |
baseRevision | Строка | Исходная конфигурация цели |
planId, planHash | Строка и SHA-256 | Проверенный план при запуске |
jobId | Строка | Существующее задание при чтении/продолжении |
deadlineAt | RFC 3339 | Срок запроса |
targets | Ограниченный массив | Узлы и желаемые artifacts |
parameters | Типизированный объект профиля | Проверяемые входные значения |
План возвращает planId, planHash, исходную базу, проверки, упорядоченные шаги, требуемые права и восстановление. Изменение параметра или исходной базы создаёт новую редакцию плана. job.start принимает hash успешно проверенного плана и фиксирует субъект подтверждения.
15.2. Состояния и ошибки
| Состояние | Значение | Допустимое продолжение |
|---|---|---|
prepared | Кандидат сформирован | Проверка |
validated | Проверки плана завершены | Подтверждение применения |
running | Выполняются шаги | Наблюдение, допустимая отмена |
waiting | Ожидается цель или условие | Readback и возобновление |
succeeded | Обязательные шаги подтверждены | Завершение ввода |
failed | Получено отклонение | Диагностика и допустимое восстановление |
cancelled | Работа завершена по отмене | Новый план по фактической базе |
rolled_back | Предыдущий состав подтверждён | Новый план |
Коды: VALIDATION_ERROR, ACCESS_DENIED, BASE_CONFLICT, TARGET_BUSY, ARTIFACT_MISMATCH, TARGET_UNAVAILABLE, STEP_TIMEOUT, READBACK_MISMATCH, RECOVERY_FAILED. Ответ содержит путь поля/шаг, причину, фактическую редакцию при конфликте и допустимое действие. Конкурирующее изменение одной цели разрешается владельцем задания через блокировку и проверку исходной базы.
После restart координатор читает устойчивое состояние и проверяет фактическую цель. Возобновление сохраняет job ID, plan hash и завершённые шаги. Частичное применение возвращает результаты каждого шага; восстановление подтверждается readback предыдущего состава.
16. X14 — Испытательный прогон
D08-X14. X14 · Испытательный прогон — последовательность и наблюдаемый результат.
Контракт green-robot.test-run/1.0 определяет операции environment.create, environment.get, run.start, run.get, run.events, run.stop, environment.reset, run.export и environment.remove.
| Поле | Тип/содержание | Правило |
|---|---|---|
schema, requestId, operation | Версия, ID, операция | Проверка и повтор запроса |
environmentId | Строка | Выбранная виртуальная среда |
profileId, profileRevision | Строки | E-профиль и версия |
runId | Строка | Прогон при чтении/остановке/экспорте |
scenarioId, scenarioRevision | Строки | Контрольная последовательность |
participants | Массив manifest | Артефакт, метод исполнения и периферия |
initialStateHash | SHA-256 | Определённое исходное состояние |
clock | Объект режима времени | Шаг и начальный момент |
seed | Целое при использовании | Повтор случайного входа |
methods | Список T-методов | Предмет прогона |
limits | Время, память, журнал | Ресурсная граница |
Прогон проходит подготовку, готовность, выполнение, завершение или остановку. Каждый метод возвращает PASS/FAIL/NOT_RUN, причину, ожидаемое и фактическое значение, допуск, временные отметки и ссылки на доказательства. В доказательстве указаны путь, размер, SHA-256, тип и происхождение.
Экспорт содержит manifest среды, participants, сценарий, результаты и инструкцию повторения. Сброс восстанавливает исходный hash и проверяет готовность участников. Удаление среды завершает её ресурсы после сохранения предусмотренных результатов. Ошибка подготовки отличается от функционального FAIL проверяемого метода.
17. Проверка интеграции
Для каждого X-интерфейса интегратор фиксирует производителя, потребителя, schema/digest, профиль транспорта, права, положительный пример, ошибочный пример и способ восстановления. Два участника проверяются на одной редакции контракта. Несовместимый переход оформляется новой версией, миграцией и обновлением D13.
Контрольный набор D16 включает повтор, устаревшую базу, истечение срока, отказ доступа, нарушение типа/размера, прерывание процесса и повторное соединение. Результат связывает каждый пример с точными артефактами и наблюдаемой квитанцией.
Термины и сокращения
| Обозначение | Значение |
|---|---|
API | Программный интерфейс взаимодействия компонентов. |
HMI | Операторский человеко-машинный интерфейс. |
PLC | Программируемая логика контроллера и её прикладной цикл. |
CANopen | Профиль обмена по CAN со словарём объектов, состояниями и сервисами. |
MQTT | Протокол обмена сообщениями через брокер; в данном профиле используется версия 5. |
SHA-256 | Алгоритм контрольной суммы. Значение в манифесте связывает точные байты артефакта. |
digest | Контрольная сумма данных или артефакта по указанному алгоритму. |
readback | Обратное чтение фактического состояния или выполняемой версии у её источника. |
health | Проверка состояния процесса или компонента. |
endpoint | Конечная точка обмена или присоединяемый участник, определённый контекстом интерфейса. |
principal | Идентичность участника, которой назначается область доступа. |
TTL | Срок действия сообщения, команды или временного разрешения. |
SSE | Поток серверных событий по HTTP для обновления клиентского представления. |
SBOM | Ведомость программного состава с версиями и лицензиями зависимостей. |
RPO | Целевой допустимый интервал потери данных при восстановлении. |
RTO | Целевое время восстановления функции. |
seed | Начальное значение генератора случайной последовательности для повторения сценария. |
staging | Подготовленная область пакета или конфигурации перед активацией. |
rollback | Возврат к определённому предыдущему согласованному состоянию. |
snapshot | Согласованный снимок состояния на определённый момент. |
manifest | Манифест: описание состава, версий, контрольных сумм и зависимостей. |
frontend | Клиентская часть приложения, формирующая пользовательский интерфейс. |
Runtime | Среда исполнения и общие программные службы приложения. |
PASS | Метод выполнен, его критерии подтверждены. |
FAIL | Получено отклонение от заданного критерия. |
NOT_RUN | Пропуск метода в данном прогоне с указанием причины и применимости. |
QoS | Уровень качества транспортной доставки, определённый протоколом. |
Сведения о редакции
| Редакция | Применимость и содержание |
|---|---|
| 2.0 · 13.09.2026 | Проектная редакция. Профиль GR-FP-1.0. Данные и программные интерфейсы: функции, параметры, процедуры и проверяемые результаты. |