UMEC MQTT Connector Protocol v3

UMEC MQTT v3 — публичный контракт подключения устройства к UMEC Space Light. Он не совместим с внутренним MQTT API Manager и его topic-моделью или учётными данными.

Быстрый старт

Перед подключением оператор создаёт device identity, его ACL, учётные данные устройства и сопоставление с asset. Не публикуйте credentials в Git, образах, журналах или примерах.

1. Получите у оператора tenant, deviceId, отдельные username/password и сведения о TLS.
2. Подключитесь к mqtt.iot.umec.space:8883 с TLS 1.2+; anonymous access отключён.
3. Подпишитесь на <tenant>/<deviceId>/p2d.
4. Публикуйте inventory и state только в <tenant>/<deviceId>/d2p с QoS 1 и retain=false.
5. Обрабатывайте P2D config, command и ack; для записи команды храните correlation ID и отправляйте подтверждение состояния.

Проверка: broker принимает подключение по TLS, D2P сообщение проходит JSON Schema, а asset получает ожидаемое состояние. Полную модель сообщений см. в нормативном reference.

Transport и topics

Параметр	Требование
Endpoint	mqtt.iot.umec.space:8883
Transport	MQTT over TLS, TLS 1.2 или новее
Authentication	персональные username/password; anonymous access запрещён
Topic shape	<tenant>/<deviceId>/<d2p|p2d>
QoS	1 для inventory, state, config, command и ack
Retain	всегда false
Максимальный payload	1 MiB
Telemetry batch	до 1000 sensor/parameter/error points

d2p означает device-to-platform: устройство имеет только право write. p2d означает platform-to-device: устройство имеет только право read.

# Приём platform-to-device сообщений — безопасно, без секретов в примере
mosquitto_sub -h mqtt.iot.umec.space -p 8883 \
  --cafile /path/to/ca.pem \
  -u '<device-username>' -P '<device-password>' \
  -q 1 -t '<tenant>/<deviceId>/p2d'

Первое D2P state сообщение

Все v3 requests — JSON-RPC 2.0 objects с числовым id, method и params.timestamp (Unix epoch в миллисекундах).

{
  "jsonrpc": "2.0",
  "id": 1001,
  "method": "state",
  "params": {
    "timestamp": 1760000000000,
    "device": {
      "id": "<deviceId>",
      "sensors": [
        {"id": "temperature", "value": 21.6}
      ]
    }
  }
}

mosquitto_pub -h mqtt.iot.umec.space -p 8883 \
  --cafile /path/to/ca.pem \
  -u '<device-username>' -P '<device-password>' \
  -q 1 -r false \
  -t '<tenant>/<deviceId>/d2p' \
  -m @state.json

state применяют для delta и full snapshot. Отдельный флаг формата snapshot в опубликованной v3 schema не определён: используйте только согласованную модель device/modules; не добавляйте неподтверждённые поля.

Входящие P2D сообщения

Method	Направление	Назначение
config	P2D	Конфигурация, опубликованная платформой для устройства
command	P2D	Команда управления с числовым correlation ID
ack	P2D	Подтверждение или результат командного flow

Устройство не публикует P2D и не подписывается на D2P других devices. Не используйте wildcard topics.

Command lifecycle

1. Платформа публикует command в P2D с JSON-RPC id.
2. Устройство валидирует method, timestamp и свои допустимые controls.
3. Одинаковый command ID для одной пары tenant/deviceId не выполняется повторно в течение 300 секунд.
4. accepted означает, что команда принята в очередь. applied подтверждается только соответствующим state echo. При ошибке возвращается JSON-RPC error; устройство не подменяет ошибку успешным ACK.
5. При timeout применяйте ограниченную policy retry с тем же correlation ID только если операция идемпотентна. Не создавайте новый command ID для маскировки неизвестного результата.

Provisioning и отзыв доступа

Provisioning выполняет оператор или automation с необходимыми правами:

1. Создаёт физическую identity и v3 logical device identity.
2. Выдаёт ACL строго для tenant/deviceId/d2p (device write) и tenant/deviceId/p2d (device read).
3. Создаёт отдельные server principals: ingest читает D2P, publisher пишет P2D.
4. Создаёт сопоставление актива и проверяет, что сообщения inventory и state попадают в нужный актив.
5. Передаёт device credentials вне Git и журналов, проверяет TLS connection.
6. При компрометации немедленно отзывает credentials и ACL, затем выпускает новую пару credentials и повторяет проверку.

Node.js

import mqtt from 'mqtt';

const client = mqtt.connect('mqtts://mqtt.iot.umec.space:8883', {
  username: process.env.UMEC_MQTT_USERNAME,
  password: process.env.UMEC_MQTT_PASSWORD,
  protocolVersion: 4,
  rejectUnauthorized: true
});

client.on('connect', () => {
  client.subscribe('<tenant>/<deviceId>/p2d', {qos: 1});
  client.publish('<tenant>/<deviceId>/d2p', JSON.stringify({
    jsonrpc: '2.0', id: 1001, method: 'state',
    params: {timestamp: Date.now(), device: {id: '<deviceId>'}}
  }), {qos: 1, retain: false});
});

WirenBoard

Создавайте non-secret пакет конфигурации через bridge helper. Он генерирует templates без Wi‑Fi secrets, MQTT passwords, service tokens и private keys.

npm run wirenboard:publisher-setup -- \
  --tenant-id '<tenant>' \
  --physical-device-id '<physical-device-id>' \
  --sensor-ids temperature \
  --command-ids cmd-1

Совместимость

	UMEC MQTT v3	Внутренний MQTT API Manager
Назначение	публичное подключение устройства к UMEC	внутренний Manager API для provisioned controls
Topics	<tenant>/<deviceId>/d2p и p2d	internal attribute-event topics
Авторизация	ACL v3 broker	service client Manager
Учётные данные	device/server principals v3	отдельная service identity
Смешивание	запрещено	запрещено

Не используйте internal Manager topic как альтернативу публичному D2P/P2D broker. Он не получает ACL public v3 broker.

Диагностика

Симптом	Причина	Безопасное исправление
Не подключается	неверный TLS, порт или credentials	проверить hostname, CA и выданную identity; не отключать TLS verification
Publish отклонён	неправильное направление, QoS/retain или ACL	использовать строго D2P, QoS 1, retain false; запросить проверку ACL
Command повторяется	повторный ID вне правила или устройство не сохраняет dedup state	дедуплицировать id 300 секунд и подтверждать фактическим state echo
Нет истории	state не прошёл проверку схемы или ограничений либо отсутствует сопоставление актива	проверить JSON, сократить пакет до 1000 точек, проверить сопоставление

Контракт и conformance examples: JSON Schema, reference.