ZigBee/Topics

---

Общие сведения

В случае, если используется кластеризация, ко всем MQTT-топикам в приведенных ниже примерах после .../zigbee/ должно быть добавлено уникальное имя нужного "инстанса", например:

homed/fd/zigbee/myInstanceName/0c:ef:f6:ff:fe:6b:d0:29

Топики управления

homed/command/zigbee

В этот топик можно публиковать базовые команды для управления HOMEd ZigBee и сетью.

---

setPermitJoin

Эта команда управляет режимом сопряжения, то есть разрешает или запрещает новым устройствам добавляться в сеть. Пример сообщения:

{
  "action": "setPermitJoin",
  "enabled": true
}

enabled - разрешение добавления новых устройств в сеть, true - можно, false - нельзя

---

togglePermitJoin

Эта команда включает режим сопряжения, если он был выключен и наоборот. Пример сообщения:

{
  "action": "togglePermitJoin"
}

---

removeDevice

Команда для удаления устройства из базы данных, например, если устройство больше не нужно. После удаления устройство может быть повторно добавлено.

Пример сообщения:

{
  "action": "removeDevice",
  "device": "kitchenWindowSensor",
  "force": false
}

device - адрес или имя устройства‎, которое нужно удалить
force - принудительное удаление, true - удалить без отправки запроса на выход из сети, false - сначала отправить запрос

Поля action и device являются обязательными. Если поле force отсутствует в сообщении, перед удалением устройства из базы данных ему будет отправлен запрос на выход из сети.

---

setDeviceName

Команда для присвоения имени устройству. Имена отображаются в логе и базе данных, а так же могут быть использованы в топиках homed/fd/zigbee и homed/td/zigbee вместо адресов устройств.

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

Пример сообщения:

{
  "action": "setDeviceName",
  "device": "00:12:4b:00:22:60:67:df",
  "name": "roomWindowSensor"
}

device - адрес или текущее имя целевого устройства‎
name - новое имя устройства‎

Поля action и device являются обязательными. Если поле name отсутствует в сообщении, имя устройства будет удалено.

---

setupDevice

Эта команда позволяет повторно произвести настройку устройства, как это делается во время интервью.

Пример сообщения:

{
  "action": "setupDevice",
  "device": "hallDoorSensor",
  "reportings": false
}

device - адрес или имя целевого устройства‎
reportings - восстановление параметров отправки отчетов по умолчанию, true - восстановить, false - оставить как есть

Поля action и device являются обязательными. Если поле reportings отсутствует в сообщении, параметры отправки отчетов не будут изменены.

---

setupReporting

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

{
  "action": "setupReporting",
  "device": "kitchenThermometer",
  "endpointId": 2,
  "reporting": "temperature",
  "minInterval": 15,
  "maxInterval": 300,
  "valueChange": 10
}

device - адрес или имя целевого устройства‎
endpointId - конечная точка целевого устройства
reporting - название нужного отчета конечной точки, как в библиотеке устройств
minInterval - минимальный интервал отправки отчета в секундах
maxInterval - максимальный интервал отправки отчета в секундах
valueChange - минимальное изменение значения аттрибута, необходимое для отправки отчета

Поля action и device являются обязательными. Если поля endpointId и/или reporting отсутствуют в сообщении, новые параметры будут применены ко всем конечным точкам и/или отчетам соответственно. В случае отсутствия остальных полей, соответствущие им параметры не будут изменены.

---

bindDevice

Эта команда позволяет настроить биндинг между двумя устройствами или между устройством и группой.

Биндинг это функция ZigBee сети, позволяющая устройствам управлять другими устройствами или группами напрямую, минуя координатор. Например, можно настроить биндинг между выключателем и лампочкой и выключатель сможет управлять лампочкой, даже если координатор будет выключен или сервис остановлен.

Пример сообщения для настройки биндинга между двумя устройствами:

{
  "action": "bindDevice",
  "device": "roomSwitch",
  "endpointId": 2,
  "clusterId": 6,
  "dstDevice": "roomLight",
  "dstEndpointId": 1
}

Пример сообщения для настройки биндинга между устройстом и группой:

{
  "action": "bindDevice",
  "device": "hallSwitch",
  "endpointId": 1,
  "clusterId": 8,
  "groupId": 7
}

Общие поля:
device - адрес или имя целевого устройства (которое будет отправлять команды‎)
endpointId - конечная точка целевого устройства (которое будет отправлять команды‎)
clusterId - идентификатор кластера, для которого осуществляется биндинг

Поля для биндинга между устройствами:
dstDevice - адрес или имя устройства, которое будет принимать команды
dstEndpointId - конечная точка устройства, которое будет принимать команды‎

Поле для биндинга между устройством и группой:
groupId - идентификатор группы, которая будет принимать команды

Все поля, кроме dstAddress и dstEndpointId, являются обязательными. В случае, если поле dstAddress отсутствует в сообщении, устройством, принимающим команды, будет назначен координатор. Если отсутствует поле dstEndpointId, то конечной точкой устройства, принимающего команды, будет назначена конечная точка по умолчанию, то есть 1.

---

unbindDevice

Эта команда позволяет удалить биндинг между двумя устройствами или между устройством и группой.

Пример сообщения для удаления биндинга между двумя устройствами:

{
  "action": "unbindDevice",
  "device": "roomSwitch",
  "endpointId": 2,
  "clusterId": 6,
  "dstDevice": "hallLight",
  "dstEndpointId": 1
}

Пример сообщения для удаления биндинга между устройстом и группой:

{
  "action": "unbindDevice",
  "ieeeAddress": "hallSwitch",
  "endpointId": 1,
  "clusterId": 8,
  "groupId": 7
}

Все поля для этой команды идентичны полям команды настройки биндинга.

---

addGroup

Команда для добавления конечной точки устройства в группу. Группы это функция ZigBee сети, позволяющая управлять несколькими конечными точками разных устройств при помощи одночных команд. Одна и та же конечная точка может одновременно находиться в нескольких группах.

Пример сообщения:

{
  "action": "addGroup",
  "device": "kitchenLight",
  "endpointId": 2,
  "groupId": 6
}

device - адрес или имя целевого устройства
endpointId - конечная точка целевого устройства‎, которую нужно добавить в группу
groupId - идентификатор группы

Все поля, кроме endpointId являются обязательными. Если поле endpointId отсутствует в сообщении, в группу будет добавлена конечная точка по умолчанию, то есть 1.

---

removeGroup

Команда для удаления конечной точки устройства из группы. Пример сообщения:

{
  "action": "removeGroup",
  "device": "bathroomLight",
  "endpointId": 2,
  "groupId": 6
}

device - адрес или имя целевого устройства‎
endpointId - конечная точка целевого устройства‎, которую нужно удалить из группы
groupId - идентификатор группы

Все поля, кроме endpointId являются обязательными. Если поле endpointId отсутствует в сообщении, из группы будет удалена конечная точка по умолчанию, то есть 1.

---

removeAllGroups

Команда для удаления конечной точки устройства из всех групп. Пример сообщения:

{
  "action": "removeAllGroups",
  "device": "hallLight",
  "endpointId": 2
}

device - адрес или имя целевого устройства‎
endpointId - конечная точка целевого устройства‎, которую нужно удалить из всех групп

Поле ieeeAddress является обязательным. Если поле endpointId отсутствует в сообщении, из всех групп будет удалена конечная точка по умолчанию, то есть 1.

---

otaUpgrade

Команда для обновления прошивок устройств "по воздуху". Описание добавлю позже.

---

getProperties

Команда для запроса актуального (последнего известного) состояния устройства. Описание добавлю позже.

---

touchLinkScan

Эта команда позволяет определить адреса и каналы устройств, находящихся в непосредственной близости к координатору, при помощи техногогии TouchLink (если координатор и устройства ее поддерживают).

Пример сообщения:

{
  "action": "touchLinkScan"
}

К сожалению текущая реализация сервиса позволят увидеть результат сканирования только в логе, а выглядит это приблизительно так:

...
2022.09.28 11:03:40.798 (inf) zigbee:    TouchLink scan started...
2022.09.28 11:03:40.862 (inf) zigbee:    TouchLink scan response received from device "84:2e:14:ff:fe:fb:ef:b5" at channel 11
2022.09.28 11:03:41.967 (inf) zigbee:    TouchLink scan finished successfully
...

---

touchLinkReset

Эта команда позволяет осуществить сброс устройства, находящегося в непосредственной близости к координатору, к заводским настройкам при помощи техногогии TouchLink (если координатор и устройство ее поддерживают).

Пример сообщения:

{
  "action": "touchLinkReset",
  "ieeeAddress": "84:2e:14:ff:fe:fb:ef:b5",
  "channel": 11
}

ieeeAddress - адрес целевого устройства‎
channel - номер канала ZigBee, который использует устройство

Все поля являются обязательными.

---

homed/td/zigbee/00:12:4b:00:09:fe:10:9f

В этот топик можно публиковать сообщения для управления отдельным устройством (в данном примере - устройством с адресом 00:12:4b:00:09:fe:10:9f). Действия можно отправлять как по одиночке, так и кучей, на устройство они будут переданы по очереди.

В случае, если устройство имеет несколько конечных точек, поддерживающих одни и те же действия, для управления конкретной конечной точкой в конец топика нужно добавить еще один уровень, содержащий в себе номер нужной конечной точки, иначе действия будут применены ко всем конечным точкам, поддерживающим эти действия. В данном примере для конечной точки 2 топик должен выглядеть как homed/td/zigbee/00:12:4b:00:09:fe:10:9f/2.

Вместо адреса устройства в топике можно использовать его имя, например: homed/td/zigbee/tableLightLeft или homed/td/zigbee/hallOutlet/1.

Пример сообщения:

{
  "status": "on",
  "level": 150,
  "color": [63, 205, 132]
}

---

homed/td/zigbee/group/4

В этот топик можно публиковать сообщения для управления группой устройств (в данном примере - группой 4). Действия можно отправлять как по одиночке, так и кучей, на устройства они будут переданы по очереди.

Пример сообщения:

{
  "status": "on",
  "colorTemperature": 460
}

Топики состояния

homed/event/zigbee

В этот топик публикуются события в сети, такие как присоединение нового устройства или статус интервью. В случае, если устройству было присвоено имя, оно будет использоваться в поле device вместо адреса.

Пример сообщения:

{
  "device": "a4:c1:38:82:86:ee:94:7f",
  "event": "interviewFinished"
}

---

homed/expose/zigbee

Описание добавлю позже.

homed/service/zigbee

В этот топик публикуется состояние доступности сервиса.

В случае, если брокер поддерживает функцию Last Will Message и сервис "упадет" или потеряет связь с брокером, сообщение со статусом "offline" опубликуется автоматически.

Пример сообщения:

{
  "status": "online"
}

---

homed/status/zigbee

В этот топик сервис публикует содержимое файла базы данных устройств. Сообщения публикуются при добавлении/удалении устройств или раз в минуту.

---

homed/device/zigbee/f4:ce:36:d9:94:e0:58:bb

В этот топик публикуются сведения о доступности устройства (в данном примере - устройства с адресом f4:ce:36:d9:94:e0:58:bb).

Доступность устройств определяется по времени, прошедшему с момента, когда от устройства в последний раз были получены какие-либо данные. Для батарейных устройств по умолчанию это время равно 8 часам, для роутеров и устройств с питанием от сети - 10 минутам. Это время может быть скорректировано индивидуально для кажого устройства при помощи опции availability.

В случае, если параметр names в секции [mqtt] файла конфигурации настроен как true, вместо адреса устройства в топике будет использоваеться его имя, например: homed/device/zigbee/hallTemperature.

Пример сообщения:

{
  "status": "online"
}

---

homed/fd/zigbee/00:12:4b:00:0e:24:da:ac

В этот топик публикуются свойства устройства (в данном примере - устройства с адресом 00:12:4b:00:0e:24:da:ac). Дополнительное поле linkQuality содержит информацию о качестве связи с устройством. Для разных моделей координаторов это значение может иметь разный диапазон, но одно известно точно - чем больше значение, тем лучше связь.

В случае, если устройство имеет несколько конечных точек с идентичными свойствами и соответствующую конфигурацию в библиотеке, эти свойства будут публиковаться в отдельные топики, cодержащие в себе номер конкретной конечной точки. В данном примере для конечной точки 3 топик будет выглядеть как homed/fd/zigbee/00:12:4b:00:0e:24:da:ac/3.

В случае, если параметр names в секции [mqtt] файла конфигурации настроен как true, вместо адреса устройства в топике будет использоваеться его имя, например: homed/fd/zigbee/kitchenThermometer или homed/fd/zigbee/roomSwitch/2.

Пример сообщения:

{
  "battery": 66,
  "humidity": 43.81,
  "linkQuality": 145,
  "temperature": 25.98
}