Интеграция периферии RS-485

Сценарий использования

Используйте этот шаблон, когда устройству WLTE с поддержкой RS-485 нужно обмениваться сырыми байтами с периферией. OpenAPI предоставляет прозрачную передачу (passthrough); он не реализует автоматически полный стек протокола Modbus.

Ваш сервис отвечает за построение полезной нагрузки прикладного протокола, CRC при необходимости, интерпретацию ответа и применение специфичных для устройства правил повторных попыток.

Рекомендуемый поток

1. Прочитайте deviceType целевого устройства из Список устройств (на английском).
2. Найдите соответствующий профиль в Список определений типов устройств (на английском).
3. Предоставляйте прозрачную передачу только когда supportedOperations содержит device.rs485.transceive.
4. Если требуется настройка скорости передачи, отдельно потребуйте device.rs485.baudRate.set и прочитайте текущее значение из Получение конфигурации устройства (на английском).
5. Отправьте сырой запрос с новым Idempotency-Key и сохраните возвращённый ID команды.
6. Анализируйте command.result.responseHex только после SUCCESS. Если статус SENT, запросите результат команды.

Пошаговая реализация

1. Проверка возможностей и конфигурации

Не выводите поддержку RS-485 из названия устройства или другой модели. Используйте supportedOperations. Изменения скорости передачи требуют device:config; прозрачная передача требует device:control.

Конечная точка скорости передачи принимает диапазон и единицы измерения, документированные в Настройка скорости передачи RS485 (на английском). Периферия и устройство должны использовать одинаковое значение.

2. Построение сырого запроса

Через REST отправьте requestHex в Команда передачи RS485 (на английском). Текущий контракт принимает непрерывную шестнадцатеричную строку от 1 до 30 байт, без пробелов, префикса 0x или разделителей.

Если периферия использует Modbus RTU, ваше приложение должно построить адрес, функцию, данные и байты CRC. OpenAPI пересылает байты и возвращает сырые байты ответа; он не проверяет регистры Modbus или семантику функции.

3. Обработка результата команды

• SUCCESS: проанализируйте result.responseHex в соответствии с протоколом периферии.
• SENT: запросите через Получение результата команды (на английском).
• FAILED: остановитесь и покажите подтверждённый сбой.
• TIMEOUT: соответствующий ответ не поступил в течение окна ожидания. Не предполагайте, что запись на периферии не удалась.

При использовании WebSocket соответствующие данные появляются в ответе операции. Поздние или незапрошенные данные RS-485 могут поступать через device.rs485.received (на английском), у которого нет воспроизведения истории.

Ключевые интерфейсы и события

Назначение	Ссылка
Подтвердить возможности устройства	Список определений типов устройств (на английском)
Отправить сырые данные через REST	Команда передачи RS485 (на английском)
Отправить сырые данные через WebSocket	Передача RS485 (на английском)
Настроить скорость передачи	Настройка скорости передачи RS485 (на английском)
Прочитать текущую конфигурацию	Получение конфигурации устройства (на английском)
Получить несопоставленные данные	Событие данных RS485 (на английском)

Сбои и восстановление

• Повторно используйте исходный ключ идемпотентности только при повторной попытке того же запроса передачи после неизвестного результата HTTP или лимита запросов.
• Считайте TIMEOUT неопределённым финальным результатом для исходной команды; повторное использование её ключа не отправляет данные заново. Генерируйте новый ключ только когда другая физическая попытка безопасна для команды периферии.
• Проверяйте в собственном анализаторе длину ответа, контрольную сумму протокола, адрес и функцию перед применением данных.
• Незамедлительно сохраняйте незапрошенные или поздние данные, если их потеря недопустима; события WebSocket не воспроизводятся повторно.
• Соблюдайте лимиты запросов на уровне операции устройства вместо того, чтобы запускать параллельные запросы передачи к одному устройству.

Соображения для продакшна

• Поддерживайте одну скоординированную очередь запросов для каждой физической шины RS-485 или устройства.
• Скрывайте конфиденциальные полезные нагрузки, если сырые данные шины могут содержать секретные значения.
• Записывайте ID команды, ключ идемпотентности, длины запроса и ответа, финальный статус и requestId; избегайте логирования учётных данных или access token.
• Тестируйте поведение при тайм-ауте и дублирующихся ответах на реальной периферии перед включением автоматических повторных попыток.

Следующие шаги

• Лимиты запросов и повторные попытки (на английском)
• Получение результата команды (на английском)
• Событие данных RS485 через WebSocket (на английском)