WF1R и RealIoT: руководство по эксплуатации

Эта инструкция предназначена для покупателя устройств RealIoT на прошивке WF1R, которые используются в системе RealIoT как Wi-Fi устройства с BLE-первичной настройкой.

В текущем коде RealIoT к этому семейству отнесены модели WF-1R-24-IP, WF-1R-220-IP и WF-1R-220-Q. Для них используется одна и та же схема BLE-настройки пользовательской конфигурации.

Общая справка по системе RealIoT доступна на сайте: https://realiot.ru/Help/system-help.html . Общие рекомендации по физическому подключению устройств RealIoT можно посмотреть здесь: https://realiot.ru/Help/physical-connection.html .

1. Что важно знать про семейство WF1R

В коде RealIoT для WF1R подтверждена следующая схема пользовательской BLE-настройки:

передаются параметры Wi-Fi;
передается адрес MQTT-брокера;
передаются параметры MQTT-протокола qos и sigEnabled;
после этого выполняется сохранение конфигурации командой commitConfig.

Ключевое отличие от других семейств: для WF1R в текущем коде не используются пользовательские BLE-сообщения powerConfig и pulseConfig. То есть у этого семейства нет пользовательской настройки порогов, входов, освещенности или периодов сна через ту форму, которая используется в RealIoT для других прошивок.

2. Как устройство настраивается

Первичная настройка выполняется по BLE. Пользователю важно знать две вещи:

устройство сначала переводится в BLE-режим локальным действием на самом устройстве;
после этого через BLE ему передаются идентификация, Wi-Fi, MQTT-сервер и протокольные параметры.

Для интеграции через приложение или внешний конфигуратор используется BLE GATT:

Service UUID: 0xFFE0
Characteristic UUID: 0xFFE1

После подключения устройство сообщает готовность:

{"v":1,"messageType":"bleReady","status":"ok"}

3. Идентификация устройства при настройке

При первичной настройке по BLE устройству передаются:

серийный номер SN;
модель устройства deviceModel;
модель прошивки firmwareModel;
тип устройства deviceType.

Для семейства WF1R поле firmwareModel должно быть равно WF1R, а поле deviceModel должно совпадать с фактической моделью из поставки.

Если настройка выполняется вручную через JSON, используется такое сообщение:

{
  "v": 1,
  "messageType": "factoryConfig",
  "payloadData": {
    "deviceType": "YOUR_DEVICE_TYPE",
    "SN": "SERIAL-NUMBER",
    "deviceModel": "WF-1R-24-IP",
    "firmwareModel": "WF1R"
  }
}

Важно: в поле deviceModel нужно указывать именно ту модель, которая относится к вашему экземпляру устройства: WF-1R-24-IP, WF-1R-220-IP или WF-1R-220-Q. Нельзя подставлять произвольное имя или другую модель из семейства. Значение deviceType тоже должно совпадать с тем типом устройства, с которым ваш экземпляр вводится в систему.

4. Какие пользовательские параметры поддерживает WF1R

В пользовательской BLE-сессии для WF1R в текущем коде подтверждены только следующие поля:

Параметр	Сообщение BLE	Смысл
`ssid`	`wifiSsidConfig`	Имя сети Wi-Fi 2.4 ГГц, к которой устройство должно подключиться.
`password`	`wifiPasswordConfig`	Пароль от Wi-Fi сети.
`server`	`serverConfig`	Адрес MQTT-брокера. В BLE-пакете он передается в формате `mqtt://...`.
`qos`	`protocolConfig`	Уровень QoS MQTT. Допустимые значения: `0`, `1`, `2`.
`sigEnabled`	`protocolConfig`	Флаг использования SIG-подписи для проверки целостности данных.

5. BLE-сообщения пользовательской настройки

Настройка Wi-Fi сети

{
  "v": 1,
  "messageType": "wifiSsidConfig",
  "payloadData": {
    "ssid": "YOUR_WIFI"
  }
}

{
  "v": 1,
  "messageType": "wifiPasswordConfig",
  "payloadData": {
    "password": "YOUR_PASSWORD"
  }
}

Настройка MQTT-брокера

{
  "v": 1,
  "messageType": "serverConfig",
  "payloadData": {
    "server": "mqtt://realiot-1.local"
  }
}

Настройка MQTT-протокола

{
  "v": 1,
  "messageType": "protocolConfig",
  "payloadData": {
    "sigEnabled": false,
    "qos": 2
  }
}

После передачи всех конфигурационных сообщений нужно отправить:

{
  "v": 1,
  "messageType": "commitConfig"
}

6. Порядок отправки команд

Для семейства WF1R пользовательская конфигурация в RealIoT уходит строго в таком порядке:

wifiSsidConfig;
wifiPasswordConfig;
serverConfig;
protocolConfig;
commitConfig.

После commitConfig устройство подтверждает запись конфигурации и обычно сразу перезапускается. Такой BLE-disconnect после успешного ACK считается нормальным.

7. Что происходит после настройки

Устройство перезапускается.
Подключается к Wi-Fi.
Подключается к MQTT-серверу.
Строит MQTT-топики по серийному номеру.
Публикует метаданные и рабочие сообщения в RealIoT.

MQTT топики

Назначение	Топик
Состояние	`wifi/<SN>`
Команда set	`wifi/<SN>/set`
Команда get	`wifi/<SN>/get`
Метаданные	`wifi/<SN>/meta`

8. Что проверять после ввода в эксплуатацию

Устройство появляется в системе с правильным серийным номером.
В карточке устройства указана правильная модель из семейства WF1R.
На MQTT приходит сообщение meta.
Устройство выходит на тот MQTT-брокер, который был передан в serverConfig.
В метаданных и рабочих сообщениях нет признаков путаницы между серийным номером, моделью и брокером.

9. Типичные ошибки

Неправильная модель в factoryConfig. Для этого семейства нужно указывать реальную модель устройства, а не просто строку WF1R.
Путаница между моделью и прошивкой. deviceModel и firmwareModel - это разные поля. Например, deviceModel может быть WF-1R-220-IP, а firmwareModel при этом должно оставаться WF1R.
Передача неподдерживаемых для WF1R полей. Для этого семейства не нужно пытаться отправлять powerConfig, pulseConfig, thresholdLux, wakeThreshold1 и подобные поля.
Неверный формат MQTT-сервера. В BLE-сообщении адрес должен уходить как строка вида mqtt://HOST.
Ожидание, что после записи BLE останется подключенным. После commitConfig устройство обычно перезагружается, и это штатное поведение.

10. Минимальный набор JSON для ввода в эксплуатацию

{
  "v": 1,
  "messageType": "factoryConfig",
  "payloadData": {
    "deviceType": "YOUR_DEVICE_TYPE",
    "SN": "3DG8-058G-608C-STPL-1R24",
    "deviceModel": "WF-1R-24-IP",
    "firmwareModel": "WF1R"
  }
}

{
  "v": 1,
  "messageType": "wifiSsidConfig",
  "payloadData": {
    "ssid": "YOUR_WIFI"
  }
}

{
  "v": 1,
  "messageType": "wifiPasswordConfig",
  "payloadData": {
    "password": "YOUR_PASSWORD"
  }
}

{
  "v": 1,
  "messageType": "serverConfig",
  "payloadData": {
    "server": "mqtt://realiot-1.local"
  }
}

{
  "v": 1,
  "messageType": "protocolConfig",
  "payloadData": {
    "sigEnabled": false,
    "qos": 2
  }
}

{
  "v": 1,
  "messageType": "commitConfig"
}

11. Итог

Устройства семейства WF1R в текущем коде RealIoT настраиваются как Wi-Fi устройства с BLE-первичной конфигурацией, где пользователь задает только Wi-Fi, MQTT-брокер и протокольные параметры.

Для этого семейства важно не путать модель устройства (WF-1R-24-IP, WF-1R-220-IP, WF-1R-220-Q) с моделью прошивки WF1R. После настройки устройство работает через MQTT-топики RealIoT, построенные по его серийному номеру.

WF1R и система RealIoT