ZigBee/Configuration: различия между версиями

Текущая версия от 13:04, 6 ноября 2024

HOMEd > ZigBee > Конфигурация

Файл конфигурации

Конфигурация HOMEd ZigBee хранится в файле /etc/homed/homed-zigbee.conf. Пример файла конфигурации:

[log]
enabled=false
timestamps=true
file=/var/log/homed.log

[mqtt]
host=localhost
port=1883
username=zigbee
password=secret
prefix=homed
instance=
names=false
debounce=true

[homeassistant]
enabled=true
prefix=homeassistant
status=homeassistant/status

[default]
discovery=true
cloud=true

[device]
database=/opt/homed-zigbee/database.json
properties=/opt/homed-zigbee/properties.json
options=/opt/homed-zigbee/options.json
ota=/opt/homed-zigbee/ota
external=/opt/homed-zigbee/external
library=/usr/share/homed-zigbee
expose=/usr/share/homed-common/expose.json
join=disabled

[gpio]
status=71
blink=83
boot=109
reset=23

[zigbee]
adapter=znp
port=/dev/ttyUSB0
baudrate=115200
panid=0x1010
channel=11
reset=flow
write=false

[security]
key=0x000102030405060708090a0b0c0d0e0f

[debug]
port=false
adapter=false
zigbee=false

При изменении содержимого файла конфигурации сервис автоматически перезапускается.

Параметры

`[log]`

параметр	описание
enabled	включение/выключение записи логов в файл
timestamps	включение/выключение меток времени при выводе лога в `stdout`
file	путь к файлу лога

`[mqtt]`

параметр	описание
host	адрес брокера
port	порт брокера
username	имя пользователя для авторизации на брокере (может быть пустым)
password	пароль для авторизации на брокере (может быть пустым)
prefix	корневой топик
instance	уникальное имя сервиса (может быть пустым), подробности ниже
names	использование имен устройств вместо адресов в MQTT-топиках
debounce	отключение повторной публикации данных в случае, если они не изменились

`[homeassistant]`

параметр	описание
enabled	включение/выключение функции Home Assistant MQTT Discovery
prefix	корневой топик для Home Assistant MQTT Discovery
status	топик для отслеживания состояния Home Assistant

`[default]`

параметр	описание
discovery	состояние функции Home Assistant MQTT Discovery для новых устройств по умолчанию
cloud	состояние функции HOMEd Cloud для новых устройств по умолчанию

`[device]`

параметр	описание
database	путь к файлу базы данных
properties	путь к файлу, в котором будут храниться акткуальные (последние известные) состояния устройств
options	путь к файлу настройки индивидуальных опций устройств
ota	путь к папке с файлами обновлений прошивок устройств
external	путь к папке пользовательских расширений библиотеки устройств
library	путь к папке библиотеки устройств
expose	путь к файлу с опциями типовых способностей устройств
join	состояние режима сопряжения после запуска координатора, возможные значения: `previous`, `enabled`, `disabled`

`[gpio]`

параметр	описание
status	порт светодиода для индикации режима добавления устройств
blink	порт светодиода для индикации активности в сети
boot	порт, к которому подключен вывод управления загрузчиком координатора
reset	порт, к которому подключен вывод управления перезагрузкой координатора

`[zigbee]`

параметр	описание
adapter	тип адаптера, возможные значения: `ezsp`, `zboss`, `zigate`, `znp`
port	последовательный порт, к которому подключен координатор или адрес для сетевого подключения
baudrate	скорость последовательного порта (при локальном подключении)
panid	идентификатор сети (в шестнадцатеричном формате, 2 байта)
channel	номер канала ZigBee
power	мощность передачи для адаптеров ezsp и znp в dBm
reset	способ управления перезагрузкой координатора, возможные значения: `gpio`, `flow`, `soft`
write	разрешение/запрет перезаписывать конфигурацию координатора, подробности ниже

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

`[security]`

параметр	описание
key	ключ сети (в шестнадцатеричном формате, 16 байт)

`[debug]`

параметр	описание
port	вывод в лог дампов данных последовательного порта
adapter	вывод в лог дампов обмена данными с координатором
zigbee	вывод в лог дампов входящих данных от устройств

GPIO

Управление GPIO осуществляется через драйвер /sys/class/gpio.

В качестве значения для каждого параметра в секции [gpio] может быть указан либо номер порта, либо путь к файлу управления портом, например: /sys/class/gpio/gpio32/value. Если используется путь к файлу управления, порт должен быть заведомо инициализирован.

Параметры status и blink могут содержать одинаковое значение, в этом случае для обоих функций будет использоваться один и тот же светодиод.

В случае, когда управление GPIO не поддерживается системой или просто не требуется, нужно либо указать значение -1 для ненужного порта, либо удалить из файла конфигурации соответствующие строки.

Сетевое подключение

HOMEd ZigBee поддерживает работу с координатором по сети, через TCP сокет, например, через ser2net в режиме RAW.

Для использования этой функции в качестве значения параметра port в секции [zigbee] нужно указать строку в формате tcp://address:port, например:

[zigbee]
...
port=tcp://192.168.1.23:4832
...

Кластеризация

HOMEd ZigBee позволяет использовать несколько "инстансов" сервиса внутри одного корневого топика, это нужно, например, для централизованного управления всеми "инстансами" из одного веб-интерфейса или для организации перекрестных автоматизаций между "инстансами".

Для корректной работы этих функций необходимо, чтобы у каждого "инстанса" было свое уникальное имя, при этом имя одного из "инстансов" может быть пустым. Остальные сервисы устроены так, что смена уникальных имен для "инстансов" не должна влиять на их работу, однако не стоит забывать, что некоторые MQTT-топики сервисов публикуются с флагом retain, поэтому переименование "инстансов" без ручной зачистки таких топиков может привести к нежелательным последсвиям.

Уникальное имя "инстанса" может быть стокой, состоящей из любых символов, за исключением спец-символов, используемых в MQTT-топиках: #, + и /. Однако, во избежание потенциальных проблем, я рекомендую использовать строки без пробелов, состоящие только из латинских букв и цифр, например: guestHouse.

Конфигурация координатора

При каждом запуске HOMEd ZigBee проверяет настройки координатора и сравнивает их с настройками, заданными в файле конфигурации. В случае, если настройки НЕ совпадают, дальнейшее поведение сервиса определяется параметром write в секции [zigbee]. Если параметр настроен как true, сервис перезапишет настройки координатора и продолжит запуск, в противном случае в логе появится запись о несовпадающем параметре и работа сервиса будет приостановлена.

Не рекомендую оставлять параметр write настроенным как true, поскольку это может привести к случайному изменению настроек координатора и необходимости повторного добавления всех устройств в сеть.

Примеры конфигурации

`HOMEd Gateway Nano`

[log]
enabled=false
file=/var/log/homed.log

[mqtt]
host=localhost
port=1883
prefix=homed
names=false

[homeassistant]
enabled=true
prefix=homeassistant
status=homeassistant/status

[default]
discovery=true
cloud=true

[device]
database=/opt/homed-zigbee/database.json
properties=/opt/homed-zigbee/properties.json
options=/opt/homed-zigbee/options.json
external=/opt/homed-zigbee/external
library=/usr/share/homed-zigbee

[gpio]
status=/sys/class/leds/amber:act/brightness
blink=/sys/class/leds/blue:zb/brightness
boot=/sys/class/gpio/zb:boot/value
reset=/sys/class/gpio/zb:reset/value

[zigbee]
adapter=znp
port=/dev/ttyS0
baudrate=115200
panid=0x1010
channel=11
reset=gpio
write=true

[security]
key=0x000102030405060708090a0b0c0d0e0f

[debug]
port=false
adapter=false
zigbee=false

`HOMEd Gateway Pico`

[log]
enabled=false
file=/var/log/homed.log

[mqtt]
host=localhost
port=1883
prefix=homed
names=false

[homeassistant]
enabled=true
prefix=homeassistant
status=homeassistant/status

[default]
discovery=true
cloud=true

[device]
database=/opt/homed-zigbee/database.json
properties=/opt/homed-zigbee/properties.json
options=/opt/homed-zigbee/options.json
external=/opt/homed-zigbee/external
library=/usr/share/homed-zigbee

[gpio]
status=/sys/class/leds/amber:status/brightness

[zigbee]
adapter=znp
port=/dev/ttyS2
baudrate=115200
panid=0x1010
channel=11
reset=soft
write=true

[security]
key=0x000102030405060708090a0b0c0d0e0f

[debug]
port=false
adapter=false
zigbee=false

`Perenio PEACG01`

[log]
enabled=false
file=/var/log/homed.log

[mqtt]
host=localhost
port=1883
prefix=homed
names=true

[homeassistant]
enabled=true
prefix=homeassistant
status=homeassistant/status

[default]
discovery=true
cloud=true

[device]
database=/opt/homed-zigbee/database.json
properties=/opt/homed-zigbee/properties.json
options=/opt/homed-zigbee/options.json
external=/opt/homed-zigbee/external
library=/usr/share/homed-zigbee

[gpio]
status=/sys/class/leds/white:power/brightness
blink=/sys/class/leds/white:wlan/brightness
reset=/sys/class/gpio/zigbee:reset/value

[zigbee]
adapter=ezsp
port=/dev/ttyUSB0
baudrate=115200
panid=0x1010
channel=11
reset=gpio
write=true

[security]
key=0x000102030405060708090a0b0c0d0e0f

[debug]
port=false
adapter=false
zigbee=false

`Xiaomi DGNWG05LM`

[log]
enabled=false
file=/var/log/homed.log

[mqtt]
host=localhost
port=1883
prefix=homed
names=false

[homeassistant]
enabled=true
prefix=homeassistant
status=homeassistant/status

[default]
discovery=true
cloud=true

[device]
database=/opt/homed-zigbee/database.json
properties=/opt/homed-zigbee/properties.json
options=/opt/homed-zigbee/options.json
external=/opt/homed-zigbee/external
library=/usr/share/homed-zigbee

[gpio]
boot=40
reset=41

[zigbee]
adapter=zigate
port=/dev/ttymxc1
baudrate=115200
panid=0x1010
channel=11
reset=gpio
write=true

[security]
key=0x000102030405060708090a0b0c0d0e0f

[debug]
port=false
adapter=false
zigbee=false

`Geniatech GTW360`

[log]
enabled=false
file=/var/log/homed.log

[mqtt]
host=localhost
port=1883
prefix=homed
names=false

[homeassistant]
enabled=true
prefix=homeassistant
status=homeassistant/status

[default]
discovery=true
cloud=true

[device]
database=/opt/homed-zigbee/database.json
properties=/opt/homed-zigbee/properties.json
options=/opt/homed-zigbee/options.json
external=/opt/homed-zigbee/external
library=/usr/share/homed-zigbee

[gpio]
status=/sys/class/leds/amber/brightness
boot=/sys/class/gpio/zigbee-boot/value
reset=/sys/class/gpio/zigbee-reset/value

[zigbee]
adapter=zboss
port=/dev/ttymxc3
baudrate=115200
panid=0x1010
channel=11
reset=gpio
write=true

[security]
key=0x000102030405060708090a0b0c0d0e0f

[debug]
port=false
adapter=false
zigbee=false

Что дальше?

После настройки HOMEd ZigBee можно приступать к добавлению устройств в сеть, при помощи веб-интерфейса или вручную.

@@ Строка 6: / Строка 6: @@
 <syntaxhighlight lang="ini">
 [log]
-enabled=true
+enabled=false
+timestamps=true
 file=/var/log/homed.log
@@ Строка 32: / Строка 33: @@
 properties=/opt/homed-zigbee/properties.json
 options=/opt/homed-zigbee/options.json
+ota=/opt/homed-zigbee/ota
 external=/opt/homed-zigbee/external
 library=/usr/share/homed-zigbee
+expose=/usr/share/homed-common/expose.json
 join=disabled
@@ Строка 70: / Строка 73: @@
   |'''enabled'''
   |включение/выключение записи логов в файл
+|-
+ |'''timestamps'''
+ |включение/выключение меток времени при выводе лога в <code class="value">stdout</code>
 |-
   |'''file'''
@@ Строка 96: / Строка 102: @@
 |-
   |'''instance'''
-  |уникальное имя сервиса (может быть пустым)
+  |уникальное имя сервиса (может быть пустым), подробности [[#Кластеризация|ниже]]
 |-
   |'''names'''
-  |использование имен устройств вместо адресов в топиках <code class="value">homed/fd/zigbee</code>
+  |использование имен устройств вместо адресов в MQTT-топиках
 |-
   |'''debounce'''
@@ Строка 136: / Строка 142: @@
   !style="width: 15%"|параметр
   !style="width: 85%"|описание
-|-
- |'''library'''
- |путь к папке библиотеки устройств
 |-
   |'''database'''
@@ Строка 144: / Строка 147: @@
 |-
   |'''properties'''
-  |путь к файлу, в котором будут храниться аеткуальные (последние известные) состояния устройств
+  |путь к файлу, в котором будут храниться акткуальные (последние известные) состояния устройств
 |-
   |'''options'''
   |путь к файлу настройки индивидуальных опций устройств
+|-
+ |'''ota'''
+ |путь к папке с файлами обновлений прошивок устройств
 |-
   |'''external'''
   |путь к папке пользовательских расширений библиотеки устройств
+|-
+ |'''library'''
+ |путь к папке библиотеки устройств
+|-
+ |'''expose'''
+ |путь к файлу с [[Common/Options|опциями]] типовых [[Common/Exposes|способностей]] устройств
 |-
   |'''join'''
@@ Строка 189: / Строка 201: @@
 |-
   |'''panid'''
-  |идентификатор сети (в шестнадцатеричом формате, 2 байта)
+  |идентификатор сети (в шестнадцатеричном формате, 2 байта)
 |-
   |'''channel'''
@@ Строка 203: / Строка 215: @@
   |разрешение/запрет перезаписывать конфигурацию координатора, подробности [[#Конфигурация координатора|ниже]]
 |}
+{{Warning|Во избежание проблем, связанных с конфликтами сетей, обязательно используйте уникальное значение параметра <code>panid</code> для каждой сети в пределах одной локации, если эти сети работают на одном канале.}}
 === <code>[security]</code> ===
@@ Строка 210: / Строка 224: @@
 |-
   |'''key'''
-  |ключ сети (в шестнадцатеричом формате, 16 байт)
+  |ключ сети (в шестнадцатеричном формате, 16 байт)
 |}
@@ Строка 248: / Строка 262: @@
 ...
 </syntaxhighlight>
+== Кластеризация ==
+{{Service|ZigBee}} позволяет использовать несколько "инстансов" сервиса внутри одного корневого топика, это нужно, например, для централизованного управления всеми "инстансами" из одного [[Web|веб-интерфейса]] или для организации перекрестных [[Automation|автоматизаций]] между "инстансами".
+Для корректной работы этих функций ''необходимо'', чтобы у каждого "инстанса" было свое уникальное имя, при этом имя ''одного'' из "инстансов" может быть пустым. Остальные сервисы устроены так, что смена уникальных имен для "инстансов" не должна влиять на их работу, однако не стоит забывать, что некоторые MQTT-топики сервисов публикуются с флагом '''retain''', поэтому переименование "инстансов" без ручной зачистки таких топиков может привести к нежелательным последсвиям.
+{{Warning|Уникальное имя "инстанса" может быть стокой, состоящей из любых символов, за исключением спец-символов, используемых в MQTT-топиках: <code>#</code>, <code>+</code> и <code>/</code>. Однако, во избежание потенциальных проблем, я рекомендую использовать строки без пробелов, состоящие только из латинских букв и цифр, например: <code>guestHouse</code>.}}
 == Конфигурация координатора ==
@@ Строка 264: / Строка 285: @@
 host=localhost
 port=1883
-username=
-password=
 prefix=homed
 names=false
-debounce=true
 [homeassistant]
@@ Строка 291: / Строка 309: @@
 boot=/sys/class/gpio/zb:boot/value
 reset=/sys/class/gpio/zb:reset/value
-join=disabled
 [zigbee]
@@ Строка 320: / Строка 337: @@
 host=localhost
 port=1883
-username=
-password=
 prefix=homed
 names=false
-debounce=true
 [homeassistant]
@@ Строка 341: / Строка 355: @@
 external=/opt/homed-zigbee/external
 library=/usr/share/homed-zigbee
-join=disabled
 [gpio]
@@ Строка 373: / Строка 386: @@
 host=localhost
 port=1883
-username=
-password=
 prefix=homed
 names=true
-debounce=true
 [homeassistant]
@@ Строка 394: / Строка 404: @@
 external=/opt/homed-zigbee/external
 library=/usr/share/homed-zigbee
-join=disabled
 [gpio]
@@ Строка 428: / Строка 437: @@
 host=localhost
 port=1883
-username=
-password=
 prefix=homed
 names=false
-debounce=true
 [homeassistant]
@@ Строка 449: / Строка 455: @@
 external=/opt/homed-zigbee/external
 library=/usr/share/homed-zigbee
-join=disabled
 [gpio]
@@ Строка 458: / Строка 463: @@
 adapter=zigate
 port=/dev/ttymxc1
+baudrate=115200
+panid=0x1010
+channel=11
+reset=gpio
+write=true
+[security]
+key=0x000102030405060708090a0b0c0d0e0f
+[debug]
+port=false
+adapter=false
+zigbee=false
+</syntaxhighlight>
+=== <code>Geniatech GTW360</code> ===
+<syntaxhighlight lang="ini">
+[log]
+enabled=false
+file=/var/log/homed.log
+[mqtt]
+host=localhost
+port=1883
+prefix=homed
+names=false
+[homeassistant]
+enabled=true
+prefix=homeassistant
+status=homeassistant/status
+[default]
+discovery=true
+cloud=true
+[device]
+database=/opt/homed-zigbee/database.json
+properties=/opt/homed-zigbee/properties.json
+options=/opt/homed-zigbee/options.json
+external=/opt/homed-zigbee/external
+library=/usr/share/homed-zigbee
+[gpio]
+status=/sys/class/leds/amber/brightness
+boot=/sys/class/gpio/zigbee-boot/value
+reset=/sys/class/gpio/zigbee-reset/value
+[zigbee]
+adapter=zboss
+port=/dev/ttymxc3
 baudrate=115200
 panid=0x1010