UMEC MQTT v3 — нормативный reference

Этот документ фиксирует только поля и ограничения, подтверждённые текущим bridge contract и JSON Schema. Если поле здесь не описано, не считайте его публичным контрактом.

Оболочка JSON-RPC

Поле	Тип	Обязательно	Правило
jsonrpc	string	да	только "2.0"
id	number	да	correlation ID; command ID дедуплицируется 300 секунд на tenant/deviceId
method	string	да	inventory, state, config, command, ack
params	object	да	содержит как минимум timestamp
params.timestamp	integer	да	Unix epoch milliseconds
params.device	object	нет	device section сообщения
params.modules	array	нет	module sections сообщения

Верхний уровень не допускает дополнительных полей. Схема: umec-mqtt-v3.schema.json.

Методы и направление

Method	Направление	Payload policy
inventory	D2P	описание identity/schema; inventory не подтверждает freshness измерения
state	D2P	измеренное состояние, delta или full snapshot
config	P2D	configuration/control, подготовленный платформой
command	P2D	writable parameter или action command
ack	P2D	acknowledgement/result flow

Для всех flows — QoS 1 и retain=false. Размер MQTT message не более 1 MiB. Сумма sensors, parameters и errors в device и modules не более 1000.

State

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

Этот пример является conformance shape: значения и codes заменяются данными конкретной device schema. Bridge сохраняет observed state отдельно от inventory; offline/unavailable state не должен фабриковать source timestamp или history datapoint.

Inventory

{
  "jsonrpc": "2.0",
  "id": 1002,
  "method": "inventory",
  "params": {
    "timestamp": 1760000000000,
    "device": {"id": "<deviceId>"},
    "modules": []
  }
}

Inventory reconciles identity/schema. Он не заменяет state и не делает контроллер или sensor fresh.

Config, command и ACK

P2D config/commands размещают device controls на верхнем уровне params; legacy params.device для этих сообщений не используйте. Каждая writable parameter, module parameter и action command — отдельный request с независимым numeric ID.

{
  "jsonrpc": "2.0",
  "id": 2001,
  "method": "command",
  "params": {"timestamp": 1760000000000}
}

Успешный admission response имеет shape { "accepted": 1 }. applied требует matching state echo. Если команда невалидна, запрещена ACL или не может быть применена, используйте JSON-RPC error, не success object.

ACL

Principal	Разрешено	Запрещено
device	write только <tenant>/<deviceId>/d2p; read только <tenant>/<deviceId>/p2d	другой device, обратное направление, wildcard
ingest	read только своего D2P topic	P2D и publish
publisher/server	write только своего P2D topic	D2P и subscribe

ACL rule не содержит + или #, имеет ровно три topic segments, tenant/deviceId совпадают с principal scope.

Retry и timeout

Timeout и retry должны быть ограничены policy устройства. Сохраняйте id, время отправки и terminal result. Повторять безопасно только идемпотентную команду с тем же ID; команду с неизвестным эффектом эскалируйте оператору. Не логируйте payload values, passwords, tokens или private keys.

Проверка перед выпуском

1. Валидируйте каждый JSON against schema.
2. Проверьте topic, QoS 1, retain false и payload ≤ 1 MiB.
3. Проверьте фактический device ACL без wildcard.
4. Проверьте D2P inventory/state, P2D command и matching state echo в staging.
5. Ротируйте credentials через provisioning flow; старые credentials отзываются до публикации новых.