diff --git a/img/web_auth_start.png b/img/web_auth_start.png new file mode 100644 index 00000000..b9723f2b Binary files /dev/null and b/img/web_auth_start.png differ diff --git a/img/web_info.png b/img/web_info.png new file mode 100644 index 00000000..386820db Binary files /dev/null and b/img/web_info.png differ diff --git a/img/web_log.png b/img/web_log.png new file mode 100644 index 00000000..2ab0047d Binary files /dev/null and b/img/web_log.png differ diff --git a/img/web_objects.png b/img/web_objects.png new file mode 100644 index 00000000..e2ba2db1 Binary files /dev/null and b/img/web_objects.png differ diff --git a/img/web_objects_create.png b/img/web_objects_create.png new file mode 100644 index 00000000..8e38cb29 Binary files /dev/null and b/img/web_objects_create.png differ diff --git a/img/web_ui_mobile.png b/img/web_ui_mobile.png new file mode 100644 index 00000000..873126af Binary files /dev/null and b/img/web_ui_mobile.png differ diff --git a/img/web_ui_pc.png b/img/web_ui_pc.png new file mode 100644 index 00000000..b55b9512 Binary files /dev/null and b/img/web_ui_pc.png differ diff --git a/img/web_zig_conf_apply.png b/img/web_zig_conf_apply.png new file mode 100644 index 00000000..3228e694 Binary files /dev/null and b/img/web_zig_conf_apply.png differ diff --git a/img/web_zig_conf_mqtt1.png b/img/web_zig_conf_mqtt1.png new file mode 100644 index 00000000..4813ff9a Binary files /dev/null and b/img/web_zig_conf_mqtt1.png differ diff --git a/img/web_zig_conf_mqtt2.png b/img/web_zig_conf_mqtt2.png new file mode 100644 index 00000000..a427d947 Binary files /dev/null and b/img/web_zig_conf_mqtt2.png differ diff --git a/img/web_zig_conf_mqtt3.png b/img/web_zig_conf_mqtt3.png new file mode 100644 index 00000000..9dddec51 Binary files /dev/null and b/img/web_zig_conf_mqtt3.png differ diff --git a/img/web_zig_config.png b/img/web_zig_config.png new file mode 100644 index 00000000..4f80dd63 Binary files /dev/null and b/img/web_zig_config.png differ diff --git a/img/web_zig_dev.png b/img/web_zig_dev.png new file mode 100644 index 00000000..14a86b2a Binary files /dev/null and b/img/web_zig_dev.png differ diff --git a/img/web_zig_dev_bind.png b/img/web_zig_dev_bind.png new file mode 100644 index 00000000..1b5283ec Binary files /dev/null and b/img/web_zig_dev_bind.png differ diff --git a/img/web_zig_dev_info.png b/img/web_zig_dev_info.png new file mode 100644 index 00000000..b943fda3 Binary files /dev/null and b/img/web_zig_dev_info.png differ diff --git a/img/web_zig_dev_join.png b/img/web_zig_dev_join.png new file mode 100644 index 00000000..33ae3919 Binary files /dev/null and b/img/web_zig_dev_join.png differ diff --git a/img/web_zig_dev_join_succ.png b/img/web_zig_dev_join_succ.png new file mode 100644 index 00000000..8e8d60cf Binary files /dev/null and b/img/web_zig_dev_join_succ.png differ diff --git a/img/web_zig_dev_opt.png b/img/web_zig_dev_opt.png new file mode 100644 index 00000000..83697136 Binary files /dev/null and b/img/web_zig_dev_opt.png differ diff --git a/img/web_zig_dev_states.png b/img/web_zig_dev_states.png new file mode 100644 index 00000000..02d7d19d Binary files /dev/null and b/img/web_zig_dev_states.png differ diff --git a/img/web_zig_dev_states_sb.png b/img/web_zig_dev_states_sb.png new file mode 100644 index 00000000..1a049a39 Binary files /dev/null and b/img/web_zig_dev_states_sb.png differ diff --git a/img/web_zig_map.png b/img/web_zig_map.png new file mode 100644 index 00000000..b4ef1d7e Binary files /dev/null and b/img/web_zig_map.png differ diff --git a/img/web_zig_rst2def.png b/img/web_zig_rst2def.png new file mode 100644 index 00000000..2141756c Binary files /dev/null and b/img/web_zig_rst2def.png differ diff --git a/img/web_zig_rst_soft.png b/img/web_zig_rst_soft.png new file mode 100644 index 00000000..7815f860 Binary files /dev/null and b/img/web_zig_rst_soft.png differ diff --git a/web_new.md b/web_new.md new file mode 100644 index 00000000..21dcbfc4 --- /dev/null +++ b/web_new.md @@ -0,0 +1,367 @@ +в разработке + +# SLS. Интерфейс управления + +Основной инструмент управления шлюзом SLS - это его веб-интерфейс. Рассмотрим в подробностях каждый его пунктик. + +## Подключение к шлюзу + +Интерфейс управления доступен по IP адресу устройства на стандартном порту HTTP (80). Также, шлюз может быть доступен по DNS имени. Для этого необходимо, чтобы в сети была настроена соответствующая служба. + +Если настроена авторизация, то при подключении необходимо ввести правильную пару логин/пароль + +![](/img/web_auth_start.png) + +## Структура меню + +- SLS +- UI +- Objects +- Zigbee + - Devices + - Join + - Map + - Config + - Reset to Default + - Soft Reset + - Start BSL +- Log +- Settings + - Network + - Time & Location + - Link + - Serial + - Services + - Users + - Hardware +- Help + - Docs + - Telegram (Support, discussions) + - Supported devices +- Actions + - Files + - Backup + - Update Firmware + - Save + - Reboot System + - Logout + +## Info + +![](/img/web_info.png) + +Стартовая страница веб-интерфейса - это страница с информацией о статусе шлюза и его подсистем: ESP32, zigbee модуля, подключения к локальной сети к внешним сервисам, синхронизации времени. Открывается, также, при нажатии на меню "SLS" + +## SLS Info + +Информация о состоянии контроллера ESP32 + +- **Version**: текущая версия прошивки. Если она актуальна, то в скобках отображается надпись `Latest`, иначе - версия актуальной прошивки в виде ссылки на форму обновления. +- **Uptime**: время, прошедшее после перезагрузки шлюза. +- **LastSave**: время, прошедшее после сохранения конфигурации. +- **FreeHeap**: количество свободной оперативной памяти в байтах. В скобках - минимум, до которого это значение опускалось в текущем сеансе. Рекомендуется ниже 100 кбайт не опускаться. Памяти может не хватать при большом количестве подключенных устройств, а также при выполнении объемных скриптов. +- **FreeHeapCommon**: объем ОЗУ. +- **TotalPsram**: объем PSRAM (Pseudostatic RAM) - это тоже память, но чуть помедленнее. Данные контроллер там размещает специальным образом, заданным программистом. +- **FreePsram**: количество свободной PSRAM. В скобках - минимум, до которого это значение опускалось в текущем сеансе. +- **Storage**: внутреннее хранилище контроллера ESP32 - флэш-память. LFS: файловая система. Если файловая система `FAT`, то очень желательно заменить её на `LittleFS` - она специально разработана для микроконтроллеров и отлично переносит холодные рестарты. Для смены файловой системы, необходимо обновить прошивку шлюза. 16Mb: объем флэшки. QOUT 80: режим доступа к SPI флэш и скорость шины. Можно менять при прошивке. Разные режимы немного отличаются по скорости. + +## Network info (WiFi) + +Здесь отображается справочная информация о подключении к локальной сети: настройки сетевого интерфейса, такие как IP (внешний и внутренний) и MAC адрес SLS, адрес маршрутизатора, и DNS серверов, маска подсети. Также, отображаются параметры подключения к сети Wi-Fi, такие как SSID, BSSID, текущий радио-канал, метод шифрования и качество WiFi соединения. + +## Zigbee info + +Информация о состоянии zigbee-модуля: + +- **Devices**: количество подключенных зигби устройств. +- **ChipType**: тип радиомодуля (например, TI CC2652). +- **IeeeAddr**: физический адрес. +- **Revision**: версия прошивки (на момент публикации статьи рекомендуемая стабильная версия 20230507). +- **PanId**: идентификатор сети ZigBee (Personal area network). +- **Channel**: частотный канал ZigBee модуля. +- **DeviceState**: статус радиомодуля. Если он отличен от 9 [ OK ], то скорее всего возникла аппаратная проблема или неверно настроены пины. + +## States + +Информация о статусе подключения к MQTT брокеру и Cloud - облаку SLS. + +- **MQTT**: статус и аптайм подключения к MQTT брокеру. Может иметь значения: + - Connected - подключен + - Disabled - отключен в настройках + - Not connected (Connect failed) - ошибка подключения (хост недоступен) + - Not connected (Unauthorized) - ошибка подключения (ошибка авторизации) +- **MQTT Prefix**: корневой топик шлюза (например ZigbeeSLS). +- **Cloud**: статус подключения к облаку SLS, для мониторинга и интеграции с внешними сервисами, например Яндекс Алиса. Может быть Connected и Disabled. Облако в перманентной разработке. + +## Settings + +Текущий статус синхронизации системных часов. Если в шлюзе не распаян модуль RTC (real time clock - часы реального времени), то для правильной работы таймеров в скриптах, обязательно должна быть настроена синхронизация с серверами точного времени. + +- **Current Time**: текущие дата и время. +- **Current TimeZone**: часовой пояс (например, UTC+5:00). +- **Current NTP server**: сервер точного времени (например, pool.ntp.org). + +_TODO: здесь будет видео с обзором данной вкладки_ + +## UI + +Шлюз SLS позволяет пользователю создать свой, альтернативный, интерфейс. Например, такой: + + + +_TODO: здесь будет ссылка на статью и видео с подробным разбором создания собственного UI_ + +## Objects + +Объекты - это универсальная сущность для хранения и обмена данными между подсистемами шлюза, например между скриптами LUA. Здесь находятся инструменты для управления объектами: + +![](/img/web_objects.png) + +Кнопки в заголовке: + +- **Refresh**: обновить список объектов. +- **Add (плюсик)**: создать новый объект. + +Поля таблицы: + +- **N**: номер по порядку (для информации). +- **Name**: имя объекта. +- **Type**: тип данных. +- **Value**: текущее значение. +- **OldValue**: предыдущее значение. +- **TS**: дата и время записи текущего значения (timestamp). +- **OldTS**: дата и время записи предыдущего значения. +- **Script**: имя скрипта, привязанного к объекту - запускается при изменении значения. +- **Flags**: флаги объекта. +- **Actions**: управление объектом. + +Кнопки в поле Actions каждого объекта: + +- **Edit (карандашик)**: редактировать объект. Открывается форма, такая же, как при создании. +- **Remove (крестик)**: удалить объект. + +### Создание и редактирование объекта + +![](/img/web_objects_create.png) + +- **Name**: имя объекта. +- **Value**: значение. +- **Ack**: флаг обратной связи. +- **Type**: тип значения объекта (STR, INT, FLOAT, BOOL, JSON). +- **Share**: сетевые флаги. Пока доступен флаг MQTT, для передачи значения объекта на MQTT брокер. +- **Script**: имя скрипта, привязанного к объекту - запускается при изменении значения. +- **Run on Write**: флаг запуска при каждой записи значения в объект, даже если оно не изменилось + +_TODO: здесь будет видео с обзором данной вкладки_ + +_TODO: здесь будет ссылка на статью и видео с подробным разбором работы с объектами._ + +## Zigbee + +Здесь собраны инструменты для работы с zigbee модулем. Структура меню: + +- Devices +- Join +- Map +- Config +- Reset to Default +- Soft Reset +- Start BSL + +### Devices + +![](/img/web_zig_dev.png) + +Список подключенных устройств. Заголовки полей таблицы кликабельны и позволяют при клике по нему отсортировать соответствующее поле. При этом рядом с таким заголовком отображается значок сортировки. + +Пробежимся по полям таблички: +- **#**: номер по порядку. +- **Pic**: изображение устройства. При наведении на него мышкой - картинка увеличивается. +- **Address**: физический адрес устройства - `ieeeAddr` (в скобках сетевой адрес - `nwkAddr`). При нажатии на него, открывается форма управления устройством. +- **Friendly Name**: дружественное имя. Желательно в латинице, но не обязательно. +- **Manuf**: идентификатор производителя устройства. +- **ModelId**: идентификатор модели устройства. +- **CID**: идентификатор конвертера. При клике по значению, откроется карточка устройства в справочнике поддерживаемых устройств. +- **Link**: уровень связи с координатором. +- **Interview**: статус прохождения интервью с координатором. +- **Last Seen**: время, прошедшее после последнего появления устройства в сети. +- **Routers**: если устройство подключено через роутер(ы), то здесь отображается его адрес, при клике по которому открывается форма управления устройством - роутером. +- **PS**: тип источника питания. Для батарейных устройств отображается уровень заряда батареи. +- **Actions**: кнопки: + - Rename device - открывает форму редактирование friendly name + - Remove device - выпадающий список с двумя вариантами удаления устройства: + - Send leave req - отправить запрос на удаление устройства с координатора + - Remove - удалить сразу. + +### Управление устройством + +Здесь находятся инструменты управления устройством и отображается различная статусная информация. + +#### Вкладка Info + +![](/img/web_zig_dev_info.png) + +Здесь выводится основная информация об устройстве. Также, здесь можно управлять конвертером, отредактировать Friendly Name и удалить устройство. Описание полей здесь такое же как и в таблице устройств. Повторятся не будем. Остановимся на описании полей, которых нет в таблице. + +- **Converter Id**: здесь по порядку: + - _Reload converter_ - по сути его сброс, при котором очищаются все состояния (states) + - _Set converter id_ - прописать номер конвертера вручную, если он не определился автоматически; и, собственно текущий номер конвертера, клик по которому открывает справочник поддерживаемых устройств. В этом же справочнике можно подобрать конвертер, если он не определился автоматически. +- **DateCode**: версия прошивки устройства. + +Далее идет описание структуры устройства по каждому Endpoint: `Profile Id`, `Device Id`, `Input clusters`, `Output clusters`. + +Внизу страницы кнопки: + +- **Rename device**: открывает форму редактирование friendly name. +- **Reload converter Id**: по сути его (конвертера) сброс, при котором очищаются все состояния (states). +- **Set converter Id**: прописать номер конвертера вручную. +- **Bind**: открывает одноименную вкладку, для настройки биндинга. +- **Remove device**: удаление устройства. + +#### Вкладка Bind + +Здесь настраивается прямой биндинг устройств. + +Протокол Zigbee поддерживает непосредственную привязку Endpoint'ов устройств, которая позволяет напрямую управлять друг другом без вмешательства координатора или любого программного обеспечения для домашней автоматизации. Далеко не все устройства имеют прошивки с поддержкой такой привязки. + +Для настройки необходимо: +- в **Source Cluster/Ep** выбрать управляющий кластер (output cluster) +- в **DstNwkAddr** выбрать управляемой устройство, в котором найден подходящий кластер (input cluster) +- в **DstEp** выбрать кластер для управления +- нажать кнопку **Bind** + +![](/img/web_zig_dev_bind.png) + +#### Вкладка States + +Здесь отображаются состояния устройства. + +![](/img/web_zig_dev_states.png) + +Возле каждого значения (`Value`) состояния есть кнопки: `Get` - выполнить команду get в конвертере, если она поддерживается, устройство вернет новое значение; `Set` - установить значение состояние вручную, если оно доступно для записи, новое значение будет записано в устройство. + +Также, на этой вкладке настраиваются автоматизации **Simple Bind**. На картинке видно правило SB напротив состояния `occupancy`. Если коротко, то правило выполняется при каждом изменении состояния. + +_TODO: здесь будет ссылка на статью и видео о SB_ + +Среди прочих состояний, стоит сказать о состоянии `last_seen`. В это состояние выводится время последнего репорта устройства в формате `unix timestamp`. По нему удобно контролировать, не отвалилось ли устройство. Например, так: + +![](.pastes\2024-03-01-10-28-05.png) + +Это код на языке программирования LUA. Подробнее в следующих публикациях. + +#### Вкладка Options + +В некоторых устройствах имеется возможность настройки параметров (options). Например, в датчике движения на картинке, можно настроить время, которое устройство будет находиться в сработке: + +![](/img/web_zig_dev_opt.png) + +### Join + +Здесь выполняется подключение новых устройств. + +![](/img/web_zig_dev_join.png) + +По кнопке **Enable Join** включается режим сопряжения, во время которого новое устройство, переведенное также, в режим сопряжения регистрируется на шлюзе. Рядом с кнопкой **Enable Join** имеется выпадающий список, из которого можно выбрать существующий роутер для подключения. Однако, рекомендуется подключаться все-таки к координатору, а влияние роутеров по максимуму минимизировать. Особенно, это важно для "вредных" устройств, которые неохотно подключаются (PTVO, например). Для этого новое устройство нужно поднести к шлюзу на минимально возможное расстояние и отключить роутеры на время сопряжения. + +В процессе сопряжения необходимо добиться сообщения _Successfully Joined_. Если процесс зависает на каком-то этапе, то нужно отключить режим сопряжения, удалить устройство и повторить. + +![](/img/web_zig_dev_join_succ.png) + +Также, шлюз поддерживает сопряжение устройств по технологии _TouchLink (Lightlink)_, которая предусматривает поиск и идентификацию устройств перед подключением и не требует дополнительного ввода устройства в режим сопряжения. Например, лампы и пульты IKEA Tradfri. + +_TODO: здесь будет видео о сопряжении нового устройства и обзором меню Devices_ + +### Map + +Здесь отображается карта zigbee сети + +![](/img/web_zig_map.png) + +Координатор обозначен символом `звезды`. От координатора расходятся лучи - линки до устройств. Линки синего цвета до роутеров, а зеленого до конечных устройств. На линках цифрой указан уровень радиосигнала. Устройства подписаны дружественным именем (`friendly name`). Если оно не задано, то сетевым адресом (`nwkAddr`). + +### Config + +Настройка zigbee модуля. + +![](/img/web_zig_config.png) + +- **Channel**: частотный канал ZigBee модуля. Доступный диапазон 11-26. Желательно использовать стандартные каналы 15, 20, 25, поскольку на нестандартных могут не работать особо капризные устройства. По умолчанию установлен канал 11, как самый дальнобойный. Если нет проблем со связью устройств, менять его не стоит. Чем меньше номер канала, тем меньше частота и тем больше покрытие (дальность) радиоканала. Важно! При смене канала придется пересобирать сеть. +- **PanId**: идентификатор сети ZigBee (Personal area network ID). Если в одной локации несколько сетей - он должен быть уникальным для каждой. Доступный диапазон 1-65535. По умолчанию - 4660 (0x1234). Важно! При смене PanID придется пересобирать сеть. + +- **MQTT messages options**: формат передаваемых данных MQTT. + +Разберем каждую опцию настроек формата: + +- **MQTT Send Raw Command**: отправка необработанных данных (RAW). +- **MQTT Send parsed JSON (Default)**: отправка обработанных данных в формате JSON. Включено по умолчанию. +- **MQTT Send parsed Attributes**: обработка (парсинг) RAW данных и отправка каждого состояния отдельной посылкой. На скриншоте ниже показана разница в данных, если включить все три варианта: RAW, JSON и обработанный RAW + +На скриншоте ниже видна разница в передаваемых данных разного формата: + +![](/img/web_zig_conf_mqtt1.png) + +- **Use FriendlyName (for MQTT Topic & HA Entity ID)**: если включено, то MQTT топики и ID сущностей в НА (Home Assistant) именуются дружественным адресом (friendly name) устройства, иначе используется `ieee` адрес. Если `friendly name` не задано, то используется `ieee` адрес. +- **Send Cache States**: отправка кэшированных данных. Например, если датчик температуры и влажности прислал только температуру, при выбранном пункте, в сообщении будет отправлено значение и температуры и кэшированное значение влажности. Если пункт не выбран - в сообщении придет только температура. Кэш записывается во флеш память каждые 30 минут. По умолчанию включено. На скриншоте ниже видно как это работает: + +![](/img/web_zig_conf_mqtt2.png) + +- **Clear states**: передавать "пустое" значение состояния click и actions, после отправки. Необходимо для систем, которые могут выполнять обработку только при изменении значения, а не при обновлении. По умолчанию включено. Может немного увеличивать трафик. На скриншоте ниже показано, как это работает: + +![](/img/web_zig_conf_mqtt3.png) + +- **Add options states to payload**: добавляет состояния опций. Например, опция реле switch_type. +- **Add friendly name to payload**: добавляет дружественное имя. +- **Add transaction number to payload**: добавляет номер транзакции (`trSeqNum`). +- **Add model name to json payload**: добавляет модель в вывод JSON (`ModelId`). +- **Add last seen to json payload**: добавляет время последнего репорта в JSON (`last_seen`). + +MQTT messages options применяются без перезагрузки, хоть веб-интерфейс об этом и "просит". Для применения настроек zigbee модуля (Chanel, PanId) перезагрузка обязательна: + +![](/img/web_zig_conf_apply.png) + +### Reset to Default + +Позволяет сбросить настройки zigbee модуля на "заводские": очищает список устройств, сбрасывает PanId и Chanel на значения по умолчанию. + +![](/img/web_zig_rst2def.png) + +### Soft Reset + +Перезапускает zigbee модуль по пину RST. Для правильной работы должен быть прописан RST пин zigbee-модуля. Подтверждение не запрашивает! + +_TODO: ссылка на hardware_ + +Для проверки корректности рестарта можно посмотреть в лог + +_TODO: ссылка на лог_ +![](/img/web_zig_rst_soft.png) + +### Start BSL + +Режим включения zigbee модуля, позволяющий обновить его прошивку "по воздуху", без программатора - Serial Bootloader (BSL и SBL - это одно и тоже. Разные вендоры не смогли определиться с одинаковой аббревиатурой). + +_TODO: здесь будет ссылка на статью и видео по обновлению прошивки модуля_ + +## Log + +![](/img/web_log.png) + +Log - журнал сообщений системы. Позволяет отслеживать события с различным уровнем детализации: Normal, Verbose, Debug. Обратите внимание на флаги [D] и [V] после штампа времени - это уровни Debug и Verbose соответственно. + +Уровень лога задаётся с помощью выпадающего списка в правой части окна: + +- **LOG_DEBUG**: уровень отладки - самый подробный лог. +- **LOG_VERBOSE**: подробный уровень. Не выводятся события с флагом [D]. +- **LOG_NORMAL**: минимум информации. Не выводятся события с флагами [D] и [V]. Данный уровень удобен для отладки скриптов LUA, поскольку здесь остается весь вывод, включая ошибки. +- **LOG_OFF**: отключение лога. + +Следует заметить, что уровень логирования устанавливается на уровне системы, а не только для отображения в веб интерфейсе. С установленным здесь уровнем лог выводится и в UDP. В теории, уменьшение детализации лога, может сэкономить ресурсы. (_TODO: здесь будет ссылка на функцию os.udplogenable()_). + +Элементы управления отображением лога в веб интерфейсе: + +- **Clear screen**: кнопка очищает окно лога. +- **Clear logs cache**: кнопка очищает буфер вывода лога. +- **Follow log**: отключает прокрутку лога в окне. + +_TODO: здесь будет видео с обзором лога_