From b38e2df51c881b84ba7875b58ef4add51d335507 Mon Sep 17 00:00:00 2001 From: Chris Jackson Date: Sat, 13 Nov 2021 10:56:13 +1300 Subject: [PATCH] Add support for listening to group addresses on Ember coordinator (#695) Signed-off-by: Chris Jackson --- .../EmberZigBeeConsoleCommandProvider.java | 16 +-- .../zigbee/ember/handler/EmberHandler.java | 100 ++++++++++++++++++ .../ember/internal/EmberConfiguration.java | 1 + .../OH-INF/thing/controller_ember.xml | 15 ++- .../zigbee/ember/EmberHandlerTest.java | 72 +++++++++++++ org.openhab.binding.zigbee/README.md | 51 +++++++-- .../zigbee/ZigBeeBindingConstants.java | 1 + .../handler/ZigBeeCoordinatorHandler.java | 4 +- 8 files changed, 235 insertions(+), 25 deletions(-) create mode 100644 org.openhab.binding.zigbee.ember/src/test/java/org/openhab/binding/zigbee/ember/EmberHandlerTest.java diff --git a/org.openhab.binding.zigbee.console.ember/src/main/java/org/openhab/binding/zigbee/console/ember/internal/EmberZigBeeConsoleCommandProvider.java b/org.openhab.binding.zigbee.console.ember/src/main/java/org/openhab/binding/zigbee/console/ember/internal/EmberZigBeeConsoleCommandProvider.java index 64da0b856..8fe4eb9fe 100644 --- a/org.openhab.binding.zigbee.console.ember/src/main/java/org/openhab/binding/zigbee/console/ember/internal/EmberZigBeeConsoleCommandProvider.java +++ b/org.openhab.binding.zigbee.console.ember/src/main/java/org/openhab/binding/zigbee/console/ember/internal/EmberZigBeeConsoleCommandProvider.java @@ -31,6 +31,7 @@ import com.zsmartsystems.zigbee.console.ember.EmberConsoleNcpChildrenCommand; import com.zsmartsystems.zigbee.console.ember.EmberConsoleNcpConfigurationCommand; import com.zsmartsystems.zigbee.console.ember.EmberConsoleNcpCountersCommand; +import com.zsmartsystems.zigbee.console.ember.EmberConsoleNcpMulticastCommand; import com.zsmartsystems.zigbee.console.ember.EmberConsoleNcpPolicyCommand; import com.zsmartsystems.zigbee.console.ember.EmberConsoleNcpRoutingCommand; import com.zsmartsystems.zigbee.console.ember.EmberConsoleNcpScanCommand; @@ -51,13 +52,14 @@ public class EmberZigBeeConsoleCommandProvider implements ZigBeeConsoleCommandProvider { @SuppressWarnings("null") - public static final List EMBER_COMMANDS = unmodifiableList(asList( - new EmberConsoleMmoHashCommand(), new EmberConsoleNcpChildrenCommand(), - new EmberConsoleNcpConfigurationCommand(), new EmberConsoleNcpCountersCommand(), - new EmberConsoleNcpPolicyCommand(), new EmberConsoleNcpRoutingCommand(), new EmberConsoleNcpScanCommand(), - new EmberConsoleSecurityStateCommand(), new EmberConsoleNcpStateCommand(), - new EmberConsoleNcpTokenCommand(), new EmberConsoleTransientKeyCommand(), new EmberConsoleNcpValueCommand(), - new EmberConsoleNcpVersionCommand())); + public static final List EMBER_COMMANDS = unmodifiableList( + asList(new EmberConsoleMmoHashCommand(), new EmberConsoleNcpChildrenCommand(), + new EmberConsoleNcpConfigurationCommand(), new EmberConsoleNcpCountersCommand(), + new EmberConsoleNcpMulticastCommand(), new EmberConsoleNcpPolicyCommand(), + new EmberConsoleNcpRoutingCommand(), new EmberConsoleNcpScanCommand(), + new EmberConsoleSecurityStateCommand(), new EmberConsoleNcpStateCommand(), + new EmberConsoleNcpTokenCommand(), new EmberConsoleTransientKeyCommand(), + new EmberConsoleNcpValueCommand(), new EmberConsoleNcpVersionCommand())); private Map emberCommands = EMBER_COMMANDS.stream() .collect(toMap(ZigBeeConsoleCommand::getCommand, identity())); diff --git a/org.openhab.binding.zigbee.ember/src/main/java/org/openhab/binding/zigbee/ember/handler/EmberHandler.java b/org.openhab.binding.zigbee.ember/src/main/java/org/openhab/binding/zigbee/ember/handler/EmberHandler.java index 89a97780d..a4e8acd39 100644 --- a/org.openhab.binding.zigbee.ember/src/main/java/org/openhab/binding/zigbee/ember/handler/EmberHandler.java +++ b/org.openhab.binding.zigbee.ember/src/main/java/org/openhab/binding/zigbee/ember/handler/EmberHandler.java @@ -12,7 +12,12 @@ */ package org.openhab.binding.zigbee.ember.handler; +import java.util.HashMap; +import java.util.HashSet; import java.util.Map; +import java.util.Map.Entry; +import java.util.Objects; +import java.util.Set; import java.util.concurrent.ScheduledFuture; import java.util.concurrent.TimeUnit; @@ -22,6 +27,7 @@ import org.openhab.binding.zigbee.ember.EmberBindingConstants; import org.openhab.binding.zigbee.ember.internal.EmberConfiguration; import org.openhab.binding.zigbee.handler.ZigBeeCoordinatorHandler; +import org.openhab.core.config.core.Configuration; import org.openhab.core.io.transport.serial.SerialPortManager; import org.openhab.core.library.types.DecimalType; import org.openhab.core.thing.Bridge; @@ -34,7 +40,10 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; +import com.zsmartsystems.zigbee.dongle.ember.EmberNcp; import com.zsmartsystems.zigbee.dongle.ember.ZigBeeDongleEzsp; +import com.zsmartsystems.zigbee.dongle.ember.ezsp.structure.EmberMulticastTableEntry; +import com.zsmartsystems.zigbee.dongle.ember.ezsp.structure.EmberStatus; import com.zsmartsystems.zigbee.dongle.ember.ezsp.structure.EzspConfigId; import com.zsmartsystems.zigbee.serialization.DefaultDeserializer; import com.zsmartsystems.zigbee.serialization.DefaultSerializer; @@ -64,6 +73,24 @@ public class EmberHandler extends ZigBeeCoordinatorHandler implements FirmwareUp private static final String ASH_RX_NAK = "ASH_RX_NAK"; private static final String ASH_TX_NAK = "ASH_TX_NAK"; + /** + * Sets the minimum size of the multicast address table + */ + private static final int GROUPS_MINIMUM = 3; + + /** + * Sets the minimum headroom in the multicast table. This allows for room for the table to grow during a session. + * Note that the table size is set only on startup since this impacts the Ember memory use. + */ + private static final int GROUPS_HEADROOM = 3; + + /** + * Sets the maximum size of the groups table. This is designed to be large enough to allow pretty much any + * configuration, but small enough that to protect against the user adding loads of random numbers or invalid + * formatting of the config string. + */ + private static final int GROUPS_MAXIMUM = 20; + private final Logger logger = LoggerFactory.getLogger(EmberHandler.class); private final SerialPortManager serialPortManager; @@ -89,6 +116,9 @@ protected void initializeDongle() { @Override protected void initializeDongleSpecific() { + EmberConfiguration config = getConfigAs(EmberConfiguration.class); + setGroupRegistration(config.zigbee_groupregistration); + if (pollingJob == null) { Runnable pollingRunnable = new Runnable() { @Override @@ -132,6 +162,36 @@ public void run() { } } + @Override + public void handleConfigurationUpdate(Map configurationParameters) { + logger.debug("{}: Ember configuration received.", nodeIeeeAddress); + + Map unhandledConfiguration = new HashMap<>(); + Configuration configuration = editConfiguration(); + for (Entry configurationParameter : configurationParameters.entrySet()) { + // Ignore any configuration parameters that have not changed + if (Objects.equals(configurationParameter.getValue(), configuration.get(configurationParameter.getKey()))) { + logger.debug("{}: Ember configuration update: Ignored {} as no change", nodeIeeeAddress, + configurationParameter.getKey()); + continue; + } + + logger.debug("{}: Ember configuration update: Processing {} -> {}", nodeIeeeAddress, + configurationParameter.getKey(), configurationParameter.getValue()); + + switch (configurationParameter.getKey()) { + case ZigBeeBindingConstants.CONFIGURATION_GROUPREGISTRATION: + setGroupRegistration((String) configurationParameter.getValue()); + break; + default: + unhandledConfiguration.put(configurationParameter.getKey(), configurationParameter.getValue()); + break; + } + + configuration.put(configurationParameter.getKey(), configurationParameter.getValue()); + } + } + @Override public void dispose() { super.dispose(); @@ -296,4 +356,44 @@ private TransportConfig createTransportConfig(EmberConfiguration config) { transportConfig.addOption(TransportConfigOption.CONCENTRATOR_CONFIG, concentratorConfig); return transportConfig; } + + private void setGroupRegistration(String groupsString) { + if (groupsString.isBlank()) { + return; + } + + logger.debug("ZigBee Ember Coordinator group registration is {}", groupsString); + ZigBeeDongleEzsp dongle = (ZigBeeDongleEzsp) zigbeeTransport; + EmberNcp ncp = dongle.getEmberNcp(); + + String[] groupsArray = groupsString.split(","); + Set groups = new HashSet<>(); + + for (String groupString : groupsArray) { + groups.add(Integer.parseInt(groupString.trim(), 16)); + } + + int multicastTableSize = groups.size() + GROUPS_HEADROOM; + if (multicastTableSize < GROUPS_MINIMUM) { + multicastTableSize = GROUPS_MINIMUM; + } else if (multicastTableSize > GROUPS_MAXIMUM) { + multicastTableSize = GROUPS_MAXIMUM; + } + logger.debug("ZigBee Ember Coordinator multicast table size set to {}", multicastTableSize); + dongle.updateDefaultConfiguration(EzspConfigId.EZSP_CONFIG_MULTICAST_TABLE_SIZE, multicastTableSize); + + int index = 0; + for (Integer group : groups) { + EmberMulticastTableEntry entry = new EmberMulticastTableEntry(); + entry.setEndpoint(1); + entry.setNetworkIndex(0); + entry.setMulticastId(group); + EmberStatus result = ncp.setMulticastTableEntry(index, entry); + + logger.debug("ZigBee Ember Coordinator multicast table index {} updated with {}, result {}", index, entry, + result); + + index++; + } + } } diff --git a/org.openhab.binding.zigbee.ember/src/main/java/org/openhab/binding/zigbee/ember/internal/EmberConfiguration.java b/org.openhab.binding.zigbee.ember/src/main/java/org/openhab/binding/zigbee/ember/internal/EmberConfiguration.java index abc7d83a1..6184ea030 100644 --- a/org.openhab.binding.zigbee.ember/src/main/java/org/openhab/binding/zigbee/ember/internal/EmberConfiguration.java +++ b/org.openhab.binding.zigbee.ember/src/main/java/org/openhab/binding/zigbee/ember/internal/EmberConfiguration.java @@ -26,4 +26,5 @@ public class EmberConfiguration { public Integer zigbee_childtimeout; public Integer zigbee_concentrator; public Integer zigbee_networksize; + public String zigbee_groupregistration; } diff --git a/org.openhab.binding.zigbee.ember/src/main/resources/OH-INF/thing/controller_ember.xml b/org.openhab.binding.zigbee.ember/src/main/resources/OH-INF/thing/controller_ember.xml index 20ebdef53..ee36852c3 100644 --- a/org.openhab.binding.zigbee.ember/src/main/resources/OH-INF/thing/controller_ember.xml +++ b/org.openhab.binding.zigbee.ember/src/main/resources/OH-INF/thing/controller_ember.xml @@ -208,11 +208,16 @@ true - - - Add a temporary install key for device installation - true - + + + Add a temporary install key for device installation + true + + + + + Registers the binding to receive group notifications. Groups are separated by a comma and must be defined in hexadecimal. + diff --git a/org.openhab.binding.zigbee.ember/src/test/java/org/openhab/binding/zigbee/ember/EmberHandlerTest.java b/org.openhab.binding.zigbee.ember/src/test/java/org/openhab/binding/zigbee/ember/EmberHandlerTest.java new file mode 100644 index 000000000..f15ba8ed3 --- /dev/null +++ b/org.openhab.binding.zigbee.ember/src/test/java/org/openhab/binding/zigbee/ember/EmberHandlerTest.java @@ -0,0 +1,72 @@ +package org.openhab.binding.zigbee.ember; + +import static org.junit.jupiter.api.Assertions.assertEquals; + +import java.util.HashMap; +import java.util.Map; + +import org.junit.jupiter.api.Test; +import org.mockito.ArgumentCaptor; +import org.mockito.Mockito; +import org.openhab.binding.zigbee.ZigBeeBindingConstants; +import org.openhab.binding.zigbee.converter.ZigBeeChannelConverterFactory; +import org.openhab.binding.zigbee.ember.handler.EmberHandler; +import org.openhab.core.config.core.Configuration; +import org.openhab.core.io.transport.serial.SerialPortManager; +import org.openhab.core.thing.Bridge; + +import com.zsmartsystems.zigbee.dongle.ember.EmberNcp; +import com.zsmartsystems.zigbee.dongle.ember.ZigBeeDongleEzsp; +import com.zsmartsystems.zigbee.dongle.ember.ezsp.structure.EmberMulticastTableEntry; +import com.zsmartsystems.zigbee.dongle.ember.ezsp.structure.EzspConfigId; + +/** + * + * @author Chris Jackson + * + */ +public class EmberHandlerTest { + class EmberHandlerForTest extends EmberHandler { + public EmberHandlerForTest(Bridge coordinator, SerialPortManager serialPortManager, + ZigBeeChannelConverterFactory channelFactory, ZigBeeDongleEzsp dongle) { + super(coordinator, serialPortManager, channelFactory); + this.zigbeeTransport = dongle; + } + + @Override + protected Configuration editConfiguration() { + return new Configuration(); + } + } + + @Test + public void setGroupRegistration() { + Bridge bridge = Mockito.mock(Bridge.class); + SerialPortManager serialPortManager = Mockito.mock(SerialPortManager.class); + ZigBeeChannelConverterFactory zigBeeChannelConverterFactory = Mockito.mock(ZigBeeChannelConverterFactory.class); + + ZigBeeDongleEzsp dongle = Mockito.mock(ZigBeeDongleEzsp.class); + EmberNcp ncp = Mockito.mock(EmberNcp.class); + Mockito.when(dongle.getEmberNcp()).thenReturn(ncp); + EmberHandler handler = new EmberHandlerForTest(bridge, serialPortManager, zigBeeChannelConverterFactory, + dongle); + + ArgumentCaptor indexCaptor = ArgumentCaptor.forClass(Integer.class); + ArgumentCaptor valueCaptor = ArgumentCaptor.forClass(EmberMulticastTableEntry.class); + + Map cfg = new HashMap<>(); + cfg.put(ZigBeeBindingConstants.CONFIGURATION_GROUPREGISTRATION, "1234,5678, 90AB ,CDEF"); + handler.handleConfigurationUpdate(cfg); + + Mockito.verify(dongle).updateDefaultConfiguration(EzspConfigId.EZSP_CONFIG_MULTICAST_TABLE_SIZE, 7); + Mockito.verify(ncp, Mockito.times(4)).setMulticastTableEntry(indexCaptor.capture(), valueCaptor.capture()); + + int[] mcastId = { 0x1234, 0x5678, 0x90AB, 0xCDEF }; + for (int cnt = 0; cnt < 4; cnt++) { + assertEquals(cnt, indexCaptor.getAllValues().get(cnt)); + assertEquals(1, valueCaptor.getAllValues().get(cnt).getEndpoint()); + assertEquals(0, valueCaptor.getAllValues().get(cnt).getNetworkIndex()); + assertEquals(mcastId[cnt], valueCaptor.getAllValues().get(cnt).getMulticastId()); + } + } +} diff --git a/org.openhab.binding.zigbee/README.md b/org.openhab.binding.zigbee/README.md index c44c0ec7e..9e1f0747b 100644 --- a/org.openhab.binding.zigbee/README.md +++ b/org.openhab.binding.zigbee/README.md @@ -141,30 +141,37 @@ Sets the Trust Centre join/rejoin mode. | `TC_JOIN_INSECURE` | Allow all joins. | | | `TC_JOIN_INSTALLCODE` | Only join with install code. | Devices attempting to join with the TC Link Key will be rejected. | +##### Group Registration (zigbee_groupregistration) + +Some devices send commands to a group address (ie using multicast addressing). This configuration allows the user to define a list of groups that the binding will listen for commands. Multiple groups can be defined - groups are separated with a comma and must be defined as a four character hexadecimal value. + +Note that this is only available for Ember coordinators. + #### Supported Coordinators The following coordinators are known to be supported. | Name and Link | Coordinator | Configuration | Comment | | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Texas Instruments CC2531EMK](http://www.ti.com/tool/cc2531emk) | [CC2531](#cc2531-coordinator) | | CC2531 is not recommended for more then 15 devices due to its less powerful MCU. Also needs extra [hardware and Z-Stack Home 1.2 firmware flashed](https://www.zigbee2mqtt.io/guide/adapters/flashing/flashing_the_cc2531.html). CC2530 and CC2538 may work too with Z-Stack Home 1.2 compatible firmware. | +| [POPP ZigBee Stick](https://www.popp.eu/zb-stick/) | [Ember](#ember-ezsp-ncp-coordinator) | 115200bps
Hardware flow control
High RAM | | [Bitron Video ZigBee USB Funkstick](https://bv.smabit.eu/index.php/smart-home-produkte/zb-funkstick/) | [Ember](#ember-ezsp-ncp-coordinator) | 57600bps
Software flow control
High RAM | | | [Elelabs ELU013/ELR023](https://elelabs.com/shop/) | [Ember](#ember-ezsp-ncp-coordinator) | 115200bps
Hardware flow control
High RAM | Both the stick and the hat can be upgraded without additional hardware, firmware available [here](https://github.com/Elelabs/elelabs-zigbee-ezsp-utility). | -| [Cortet EM358 USB Stick](https://www.cortet.com/iot-hardware/cortet-usb-sticks/em358-usb-stick) | [Ember](#ember-ezsp-ncp-coordinator) | 57600bps
Software flow control
High RAM | | +| [MeshConnect EM358 USB Stick](https://www.cortet.com/iot-hardware/cortet-usb-sticks/em358-usb-stick) | [Ember](#ember-ezsp-ncp-coordinator) | | Requires specific drivers that may not work on MacOS Monterey | | [Nortek Security & Control HUSBZB-1](https://nortekcontrol.com/products/2gig/husbzb-1-gocontrol-quickstick-combo/) | [Ember](#ember-ezsp-ncp-coordinator) | 57600bps
Software flow control
High RAM | Stick contains both Z-Wave and ZigBee. | -| [Telegesis ETRX357USB ZigBee® USB Stick](https://www.silabs.com/products/wireless/mesh-networking/telegesis-modules-gateways/etrx3-zigbee-usb-sticks) | [Telegesis](#telegesis-etrx3) | | | +| [Telegesis ETRX357USB ZigBee® USB Stick](https://www.silabs.com/products/wireless/mesh-networking/telegesis-modules-gateways/etrx3-zigbee-usb-sticks) | [Telegesis](#telegesis-etrx3) | | Not supported for ZigBee 3.0 | | [QIVICON ZigBee-Funkstick](https://www.qivicon.com/de/produkte/produktinformationen/zigbee-funkstick/) | [Telegesis](#telegesis-etrx3) | | Only working on Linux devices | | [Digi XStick](https://www.digi.com/products/xbee-rf-solutions/boxed-rf-modems-adapters/xstick) | [XBee](#digi-xbee-x-stick) | | | +| [Texas Instruments CC2531EMK](http://www.ti.com/tool/cc2531emk) | [CC2531](#cc2531-coordinator) | | CC2531 is not recommended for more then 15 devices due to its less powerful MCU. Also needs extra [hardware and Z-Stack Home 1.2 firmware flashed](https://www.zigbee2mqtt.io/guide/adapters/flashing/flashing_the_cc2531.html). CC2530 and CC2538 may work too with Z-Stack Home 1.2 compatible firmware. | #### Ember EZSP NCP Coordinator -The Ember EZSP NCP (Network Co-Processor) supports the Silabs MightyGecko (EFR32MG) and the older EM357/8 dongles with the standard NCP firmware. The thing type is `coordinator_ember`. This dongle type is recommended due to its extensive use within both the community, and commercial systems using this dongle. +The Ember EZSP NCP (Network Co-Processor) supports the SiLabs MightyGecko (EFR32MG) and the older EM357/8 dongles with the standard NCP firmware. The thing type is `coordinator_ember`. This dongle type is recommended due to its extensive use within both the community, and commercial systems using this dongle. Note that there are generally two versions of the Ember NCP firmware in use. One operates at a baud rate of 115200 with RTS/CTS flow control (i.e. hardware flow control), the other operates at a baud rate of 57600, and XON/XOFF flow control (i.e. software flow control). If you are programming your own stick (e.g. the CEL stick) then it should be advisable to use the hardware flow control version - many commercial sticks seem to use the lower speed and software flow control (e.g. Bitron and Nortek HUSBZB-1). -Firmware versions higher than 6.4.0.0 may be required to work with some newer devices (ie those conforming to the Zigbee 3.0 standard). If your dongle has older firmware then devices may appear to join the network, but will not work as they will leave the network if they do not receive updated security information. +Firmware versions higher than 6.4.0.0 may be required to work with some newer devices (i.e. those conforming to the Zigbee 3.0 standard). If your dongle has older firmware then devices may appear to join the network, but will not work as they will leave the network if they do not receive updated security information. -If the usb dongle is not recognized, it might be necessary to make the dongle's device id known to the CP240x driver by Silicon Labs: +If the USB dongle is not recognized, it might be necessary to make the dongle's device id known to the CP240x driver by Silicon Labs: - Find the device id (as listed by the command `lsusb`). For the Bitron Funkstick that might be 10c4 8b34. - Unplug the device @@ -239,7 +246,7 @@ Extract and install the TI Flash Programmer, connect the CC-Debugger trough USB, ### Devices -The following devices have been tested by openHAB users with the binding. The absence of a device in this list does not mean it will not work - if the device is a standard ZigBee device similar to ones on this list, then it should work. +The following devices have been tested by openHAB users with the binding. This list is far from exhaustive, and the absence of a device in this list does not mean it will not work - if the device is a standard ZigBee device similar to ones on this list, then it should work. It should be noted that many "new" devices (approximately newer than 2020) will require coordinators that support ZigBee 3.0. If this is not supported, then devices may briefly join the network, and then leave when they find the network does not support the newer security requirements. | Device | Description | | ---------------------------------------------- | ------------------------------------------------------------ | @@ -299,9 +306,9 @@ The following devices have been tested by openHAB users with the binding. The ab ## Discovery -Discovery is performed by putting the binding into join mode (by starting an inbox search), and then putting the device into join mode. Generally, it is best to reset the device to do this. Resetting the device ensures that it is no longer joined to a previous network, will ensure it is awake if it is a battery device, and will restart any channel and network search that the device may perform. Consult the manual of the device at hand to see how to reset it, this differs from device to device. +Discovery is performed by putting the binding into join mode (by starting an thing search), and then putting the device into join mode. Generally, it is best to reset the device to do this. Resetting the device ensures that it is no longer joined to a previous network, will ensure it is awake if it is a battery device, and will restart any channel and network search that the device may perform. Consult the manual of the device at hand to see how to reset it, this differs from device to device. -Once the binding is installed, and an adapter is added, it automatically reads all devices that are set up on the ZigBee controller and puts them in the Inbox. When the binding is put into discovery mode via the user interface, the network will have join enabled for 60 seconds. You can put it in discovery mode via the **Scan** button in the user interface. This can be found after you click the blue **+** button in the bottom right corder of the **Things** screen and then select the **ZigBee Binding**. +When the binding is put into discovery mode via the user interface, the network will have join enabled for 60 seconds. You can put it in discovery mode via the **Scan** button in the user interface. This can be found after you click the blue **+** button in the bottom right corder of the **Things** screen and then select the **ZigBee Binding**. The binding will store the list of devices that have joined the network locally between restarts to allow them to be found again later. A ZigBee coordinator does not store a list of known devices, so rediscovery of devices following a restart may not be seemless if the dongle is moved to another system. @@ -339,7 +346,7 @@ The binding will attempt to automatically detect new devices, giving them a type ### Thing Types -Currently all ZigBee things have the same thing type of `zigbee_device`. +Most ZigBee things have the same thing type of `zigbee_device`. The binding will automatically discover the device features and provide channels linked to device functionality that it is able to support. A small number of devices that require a manual thing definition may be defined in the binding to support devices that have non-standard functionality, or do not support the autodiscovery functionality provided by ZigBee. ### Channel Types @@ -469,7 +476,29 @@ log:set info com.zsmartsystems.zigbee.dongle.ember.internal.ash This will log data into the standard `openhab.log` file. There is an [online log viewer](https://opensmarthouse.org/utilities/logviewer/zigbee/) available for viewing the logs. -Note that logs can only show what is happening at a high level - it can't show all data exchanges between the device and the coordinator - just what the coordinator sends to the binding. For this reason it can be difficult to debug issues where devices are not joining the network, or other low level issues need resolving. In such cases a network sniffer log is required, which requires additional hardware and software. +Note that logs can only show what is happening at a high level - it can't show all data exchanges between the device and the coordinator - just what the coordinator sends to the binding. For this reason it can be difficult to debug issues where devices are not joining the network, or other low level issues need resolving. In such cases a network sniffer log is required, which requires additional hardware and software. Information and software required to use an Ember dongle as a sniffer can be found on the [OpenSmartHouse](https://opensmarthouse.org/blog/zigbee_network_sniffer) site. + +### ZigBee Console Commands + +The openHAB command line interface provides a number of commands to interact with the ZigBee framework. These can provide useful options for debugging when things aren't going as planned, and can also provide advanced users a means to make changes that are not possible directly through the binding. This section will provide information on a few common issues that users may come up against, but is not an exhaustive user manual for low level ZigBee commands. + +All commands described below must be preceded by the word `zigbee` on the command line. To keep the documentation concise this is omitted in the examples below. + +To list all known nodes, use the `nodes` command. This will list the nodes and endpoints of the nodes, and is often required as a first step in order to get the node ID or endpoint ID for other commands. Nodes and endpoints are often required as arguments in commands and can typically be entered in decimal or hexadecimal node number with a decimal endpoint - e.g. `0x1234/1`, or `4660/1` - both of these describe the same node/endpoint. + +#### Device Information (Fingerprint) + +In some instances a device may not work correctly. This could be because the binding had problems during initialisation, or possibly because the device supports features not implemented in the binding, or possibly the device may implement custom functionality. To understand this, there is a `fingerprint` command. This command will attempt to poll the device to get a list of all the commands and attributes that the device supports and create a concise list. Note that this may not work on all devices if the device doesn't support the functionality discovery commands. + +#### Binding and Reporting + +The binding table is used within ZigBee to configure devices to send reports to the binding when their state changes. The binding will attempt to set the required ZigBee bindings during device initialisation, but sometimes this can fail. Often this may occur on older devices that have limited memory, and only have a small number of entries in the binding table, and then manual manipulation of the table may be required. + +The binding table for a node can be displayed with the `bindtable` command. It can then be updated with the `bind` command, and bindings can be removed with the `unbind` command. + +A second part to the binding and reporting system is the reporting. The binding table tells the device where it should send reports, but the actual reports must be configured as well. Many attributes in a ZigBee cluster can be configured to send reports if their state changes, or at a periodical rate if there have been no state updates within a certain time. Analogue values can be configured so that they report if the value changes by a certain amount so that the reports do not flood the system. Care must be exercised when changing this configuration as it may interfere with the binding operation. + +The exact command required to configure reporting can depend on whether the attribute is a binary or analogue type. The console commands `subscribe` and `unsubscribe` allow the user to manipulate the reporting of an attribute, and the `reportcfg` command can be used to display the current configuration. ## Known issues diff --git a/org.openhab.binding.zigbee/src/main/java/org/openhab/binding/zigbee/ZigBeeBindingConstants.java b/org.openhab.binding.zigbee/src/main/java/org/openhab/binding/zigbee/ZigBeeBindingConstants.java index 5e04f6c3c..d102f05e7 100644 --- a/org.openhab.binding.zigbee/src/main/java/org/openhab/binding/zigbee/ZigBeeBindingConstants.java +++ b/org.openhab.binding.zigbee/src/main/java/org/openhab/binding/zigbee/ZigBeeBindingConstants.java @@ -274,6 +274,7 @@ public class ZigBeeBindingConstants { public static final String CONFIGURATION_POWERMODE = "zigbee_powermode"; public static final String CONFIGURATION_TXPOWER = "zigbee_txpower"; public static final String CONFIGURATION_MESHUPDATEPERIOD = "zigbee_meshupdateperiod"; + public static final String CONFIGURATION_GROUPREGISTRATION = "zigbee_groupregistration"; public static final String CONFIGURATION_MACADDRESS = "zigbee_macaddress"; public static final String CONFIGURATION_JOINENABLE = "zigbee_joinenable"; diff --git a/org.openhab.binding.zigbee/src/main/java/org/openhab/binding/zigbee/handler/ZigBeeCoordinatorHandler.java b/org.openhab.binding.zigbee/src/main/java/org/openhab/binding/zigbee/handler/ZigBeeCoordinatorHandler.java index c856b26d6..7328e8140 100644 --- a/org.openhab.binding.zigbee/src/main/java/org/openhab/binding/zigbee/handler/ZigBeeCoordinatorHandler.java +++ b/org.openhab.binding.zigbee/src/main/java/org/openhab/binding/zigbee/handler/ZigBeeCoordinatorHandler.java @@ -105,12 +105,12 @@ public abstract class ZigBeeCoordinatorHandler extends BaseBridgeHandler protected ExtendedPanId extendedPanId; @Nullable - private IeeeAddress nodeIeeeAddress; + protected IeeeAddress nodeIeeeAddress; @Nullable protected ZigBeeTransportTransmit zigbeeTransport; @Nullable - private ZigBeeNetworkManager networkManager; + protected ZigBeeNetworkManager networkManager; @Nullable private Class serializerClass;