Общие сведения
В случае, если используется кластеризация, ко всем топикам в приведенных ниже примерах после .../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
}