Step‐by‐Step guide for the Zigbee network configuration - ioBroker/ioBroker.zigbee GitHub Wiki

Starting point

  • The adapter is installed and has been started
  • The zigbee subsystem is not started - the Adapter shows a yellow status.
  • The coordinator is available. -- For LAN Coordinators, it is connected to the network and the Webinterface is accessible. -- For USB Coordinators, it is available together with a decent USB extension cable (> 20 cm long)

Hardware configuration UI

Determine Port and Type

Lan Coordinator

The web interface for most LAN Coordinators provides the settings to be used with Zigbee2mqtt on the interface. Fortunately, these settings are identical to the settings used in the zigbee adapter. An example is shown here:

# Serial settings
serial:
# Location of CZC
  port: tcp://192.168.2.55:6638
  adapter: zstack
  baudrate: 115200
# Disable Zigbee led?
	disable_led: false
# Set output power to max 20
advanced:
	transmit_power: 20

From these settings, we can determine that we need to set the Com port name to tcp://192.168.2.55:6638, the Type to zstack and the Baudrate to 115200 The remaining settings are optional.

USB Coordinator

The port for USB Coordinators is less easily determined. This also changes by OS:

  1. connect the coordinator the system using the USB extension cord
  2. reload the configuration page to fill the USB Selector (Note: Unfortunately, the Adapter versions 3.2.3 to 3.3.0 include a bug which prevents the adapter to fill the port selection while the zigbee subsystem is not running. This will be fixed in 3.3.1 and newer)

Linux

  1. verify software compatibility and availability of a serial port. Options for that are (all entered in a terminal on the ioBroker server):
  • verify that it was detected by entering lsusb and checking the available devices.
  • verify that a port was generated by listing the USB seria ports (ls /dev/ttyUSB* and/or ls /dev/ttyA*)
  • verify if a link to /dev/serial/by-id exists (ls /dev/serial/by-id/)

Sample output is

user@iobroker:~ $ lsusb
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 016: ID 10c4:ea60 Silicon Labs CP210x UART Bridge
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
user@iobroker:~ $ ls -al /dev/ttyU*
crw-rw---- 1 root dialout 188, 0 Dec  8 23:31 /dev/ttyUSB0
user@iobroker:~ $ ls -al /dev/ttyA*
crw-rw---- 1 root dialout 204, 74 Dec  5 21:33 /dev/ttyAMA10
user@iobroker:~ $ ls -al /dev/serial/by-id
total 0
drwxr-xr-x 2 root root 60 Dec  8 17:23 .
drwxr-xr-x 4 root root 80 Dec  8 17:23 ..
lrwxrwxrwx 1 root root 13 Dec  8 17:23 usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_ba65d1655ed8ed11ba976d6162c613ac-if00-port0 -> ../../ttyUSB0

In this example, the possible entries for port are:

  • usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_ba65d1655ed8ed11ba976d6162c613ac-if00-port0
  • /dev/ttyUSB0
  1. Either select the respective USB port from the offered list or enter the port manually.

Windows

  • No idea (upcoming)

Darwin (macOS)

  1. verify software compatibility and availability of a serial port. Options for that are:
  • verify that a port was generated by listing the USB seria ports (ls /dev/tty.usbserial*)
  • verify that the device is recognized by listing the USB devices (`ioreg -p IOUSB -l -w 0 | grep '<class')

With Darwin, the serial port ID is linked to the physical port the device is plugged into. therefore, the easiest method is the last entry in the list. As an example, part of the response to the command can look like this:

user@iobroker ~ % ioreg -p IOUSB -l -w 0 | grep '<class'
+-o Root  <class IORegistryEntry, id 0x100000100, retain 42>
  +-o AppleT8112USBXHCI@03000000  <class AppleT8112USBXHCI, id 0x100000490, registered, matched, active, busy 0 (8 ms), retain 37>
  +-o AppleT8112USBXHCI@00000000  <class AppleT8112USBXHCI, id 0x10000038e, registered, matched, active, busy 0 (24 ms), retain 37>
  +-o AppleT8112USBXHCI@01000000  <class AppleT8112USBXHCI, id 0x100000390, registered, matched, active, busy 0 (20 ms), retain 37>
  +-o AppleT8112USBXHCI@02000000  <class AppleT8112USBXHCI, id 0x100000496, registered, matched, active, busy 0 (827 ms), retain 138>
  | +-o USB2.0 Hub             @02100000  <class IOUSBHostDevice, id 0x100000a66, registered, matched, active, busy 0 (275 ms), retain 49>
  |   +-o MateView@02140000  <class IOUSBHostDevice, id 0x100000a97, registered, matched, active, busy 0 (269 ms), retain 57>
  +-o AppleEmbeddedUSBXHCIASMedia3142@08000000  <class AppleEmbeddedUSBXHCIASMedia3142, id 0x1000009a8, registered, matched, active, busy 0 (287 ms), retain 59>
  | +-o G502 HERO Gaming Mouse@08300000  <class IOUSBHostDevice, id 0x100000a2b, registered, matched, active, busy 0 (286 ms), retain 57>
  +-o AppleASMediaUSBXHCI@04000000  <class AppleASMediaUSBXHCI, id 0x100000ae8, registered, matched, active, busy 0 (56 ms), retain 47>
  | +-o Sonoff Zigbee 3.0 USB Dongle Plus@04400000  <class IOUSBHostDevice, id 0x1004a0cd8, registered, matched, active, busy 0 (52 ms), retain 24>

user@iobroker ~ % ls /dev/tty.*                         
/dev/tty.Bluetooth-Incoming-Port	/dev/tty.debug-console			/dev/tty.usbserial-440

In this example, the port to enter is /dev/tty.usbserial-440 4. Enter the port manually - The adapter usually fails to list the serial ports on Darwin.

Type selection

  1. Determine the chipset of the coordinator from the documentation. Note Neither lsusb nor the id in \dev\serial\by-id\... is guaranteed to provide any information on the zigbee chipset, as this is connected via a USBtoSerial Chip.
  • TI Chips (Typically called CC...) need TI Zstack/ccxxxx as Type,
  • Silicon Labs EZSP Chips (Typically called EFR32MG...) use either SL EFR32 (EZSP) FW 7.2.x.x or SL EFR32 (EMBER) FW 7.4.x.x as Type
  • Conbee/Raspbee (I/II/III) from Dresden Elektronik use Deconz/Conbee as Type
  • Zigate coordinators use NXP/Zigate as Type - Note: The implementation for this type is abandoned and never managed to get out of the experimental stage. Use of these coordinators for live systems is discouraged.
  • ZBoss coordinators are not currently supported in the zigbee adapter due to their implementation still being in the experimental stage. This can and will change once the implementation matures.

Network parameters

Starting with the adapter version 3.0, the zigbee adapter pre-fills the network parameters with randomized entries. As such, none of the entries need to be changed for an initial start.

Channel selection

The zigbee channel should be set to one of the ZLL compatible channels (11,15,20,25). The adapter supports this by adding a little yellow triangle to the channel selector if a channel outside of this scope is selected. For the initial start the selected channel does not matter, as it is used only to scan the channels in order to determine the best channel for the network.

##Configuration verification##

In order to verify that the configuration is correct, first the port needs to be checked that it can be accessed. Clicking this button trigger an attempt to open and connect to the configured port. On Linux and MacOS, this button does this for both USB and LAN Coordinators. On Windows, this unfortunately only works for LAN coordinators. Note that this test only verifies that the port exists and can be read from and written to. No real connection attempt is made. The area below shows the resulting output. Below is an example with first an error and then a successful attempt.

reading access rights for /dev/ttyUsb0
Error: unable to access /dev/ttyUsb0 : ENOENT: no such file or directory, access '/dev/ttyUsb0'
reading access rights for /dev/ttyUSB0
read and write access available for /dev/ttyUSB0

Once the port was verified, the actual network configuration can be checked using this button: . There are two possible outcomes - success, which results in the message Zigbee-Herdsman started successfully appearing in the log and this button disappearing from the title bar.

The other alternative is that the Network did not start. At this point, the log usually pinpoints the reason. A list of possible reasons is discussed here.

Below is an example of a successful start of the network.

overriding zigbee options with:
extPanID : a92ef4294e3afd4c
panID : 8301
channel : 25
port : /dev/ttyUSB0
adapterType : zstack
baudRate : 115200
precfgkey : 01030507090B0D0F00020406080A0C0D
flowCTRL : false
Starting Adapter npm ...
Installed Version: asgothian/ioBroker.zigbee#a09852b717a68d18e4ace3b378e44740421e1d24 (Converters 25.84.0 Herdsman 7.0.4)
Starting zigbee-herdsman...
Zigbee-Herdsman started successfully with Coordinator firmware version: ZStack3x0 : 20210708 (2-1.2.7.1)
Network parameters: panID=8301 channel=25 extendedPanID=a92ef4294e3afd4c
Unable to disable LED, unsupported function.
0 devices are part of the network

Once the configuration is verified and the zigbee subsystem is active, it is time to check the load on the zigbee channels using this button If everything works as planned a graph with the relative channel energy is displayed:

It is advised to select a channel with a low energy signature. Note If this scan is performed with an active network with a large number of router devices, the channel energy may be high. In fact, in the example above, there is an active Zigbee Network on Channel 25 with 70+ devices. If this is the network you are currently trying to configure, it is not advisable to change the channel - much of the load is the actual zigbee Network communicating.

As before, it is not advisable to stray from the standard ZLL channels (11,15,20,25)

Final start

After the channel scan and setting the correct channel, it is time to restart the zigbee subsystem, using the start/stop button (twice, once to stop, once to start) note stopping the network may take a little time. Please wait until this button (in Red, not in Orange) has reappeared and the text 'herdsman stopped!' is printed in the log before starting the network again.

If this start is also ok, it is time to set this option,

save the setting and close the configuration.

This concludes the step by step guide for intial setup of the adapter. In case of attempting to migrate a network from one system to another or from one coordinator to another some of these steps will not be necessary while others become important.

Transferring a network from one system to another.

Before going into detail with this, there is an important detail to consider. Moving an existing Zigbee Network works well when specific conditions are met:

  • The location of the Coordinator relative to the routers changes little. A few meters may be ok, but moving the Coordinator from one end of the house to the other will require additional work. This is explicitly not covered in this document.
  • Moving a network from one host to another is comparatively painless, as long as the zigbee Hardware remains the same. Performing this move while also changing the coordinator hardware may require additional steps (see the point below)
  • Changing coordinators between coordinators using the same type (Zstack, Ember, EZSP) is usually easily done. Deconz/Phoscon takes a separate role here - while it is possible to migrate a network between different conbee Sticks this is not officially supported in the zigbee Adapter.
  • Changing coordinators from one type to another usually requires all devices to be paired again with the new coordinator. This document coveres the easiest way of doing this. It may seem complex at first read, but it has proven to be the most efficient method, especially for larger networks.

Moving a network to a new host.

Requirements

  • a backup of the zigbee data files. This can be done manually by collecting all files and folders in the adapters data folder (/opt/iobroker/iobroker-data/zigbee_x with x being the instance ID on MacOS/Linux) or using the ioBroker.backitup adapter, which has a specific option to perform a zigbee backup.
  • Having a backup of the iobroker itself is optional. If no base backup is restored, the zigbee Adapter needs to be installed normally, but not configured.

Restore

  • If a full iobroker backup is used as source, ensure that the restore of the backup has completed, all adapters are ready and the system is idle. Note that in this case, it is likely that the zigbee-adapter is running, but has no active devices despite devices being present in the object tree.
  • Ensure that the zigbee adapter is running, but the zigbee subsystem is halted. If necessary, use the start/stop button from the hardware tab to stop the zigbee network.
  • Restore your backup of the zigbee data files to the adapters data folder on the new host. When a backup file from ioBroker.backitup is used, the adapter should also be used for the restore.
  • Use the read NVRam backup button to read the network configuration from the nvram backup. Note that the communication port and type are not part of this backup . Use the steps from the step-by-step guide above to determine what to enter as port. After the nvRam Backup was read, the entries for ExtPanID, PanID, Channel and TransportKey show a green checkmark. They may also show a yellow triangle - this can be ignored at this point.
  • Ensure that the network on the original host is stopped !!
  • Attempt to start the network on the new host, using the start/stop button. If everything went well, and the coordinator was not moved too far, the network should come up clean and be operational immediately.

Moving a network to a new coordinator of the same type

Replacing the coordinator with a new coordinator of the same type tends to be simple:

  • stop the network (not the adapter !)
  • disconnect the old coordinator
  • connect the new coordinator
  • reconfigure the port entry
  • start the network (not the adapter !)

There are two cases where this may not work:

  • Moving to a depreceated coordinator (cc2531, cc2538 or older EZSP Chips). As this is not a common use case, no time is spent to further investiate this. Modern coordinators are easily accessible and comparatively cheap, so there is no reason to shift to one of the deprecated coordinators.
  • Moving to a network coordinator with a ExtPanID already set on the coordinator. This poses a problem as the ExtPanID is part of the network encryption, so the network may refuse the new coordinator and block the startup. The easiest method of getting around this is to clear the ExtPanID from the coordinator memory on the network coordinator. Please refer to the documentation of the coordinator for the steps needed to do this. Note Not all network coordinators use this feature. At this point, there is no definite list of coordinators which will be affected by this.

In any case, the log from Test and Verification should provide information on the network status and, if applicable, why it refuses to start.

Moving a network to a coordinator of a different type / Shifting to new encryption settings (ExtPanID, PanID)

This task usually requires all devices to be removed from the old network and then paired to the new network. This can be tricky for devices which are difficult to access. There is a workaround which seems to work for about 95% of all router devices and about 50% of all EndDevices. It takes advantage of the fact that router devices will go into pairing mode immediately after being removed from a network. In order to make use of this fact, both the old and the new network must be active at the same time, and the new network needs to be in pairing mode, ready to accept the device which just entered pairing mode. Note that this usually works even if both zigbee instances are set to the same channel.

  1. Add another instance of the zigbee Adapter to the current host.
  2. Start this instance, but do not configure it (yet)
  3. copy all files from the data folder of the original instance to this new instances data folder. (copy, not move)
  4. stop the original instance
  5. configure the new instance (see the Restore section from moving to a new host)
  6. start the new zigbee instance.
  7. configure the original instance to work with the new coordinator / with the new network encryption parameters. Do not start the zigbee network at this time.
  8. perform a full reset on the original instance (This button, select 'HARD RESET' from the dialog. If this fails, manually delete the files shepherd.db and nvbackup.json from this instances data folder.
  9. Start the network. It should come up with no devices in the network. note At this point, all device objects for this instance are still present in the object tree.

At this time, there should be two zigbee instances running. The original instance, which was restarted with the new coordinator / new parameters (called Target instance) and the duplicated instance with all the paired devices using the old coordinator (called source instance).

The next steps should be done in 'batches', going through the list of devices paired to the sourece instance. Ideally, start with the devices closest to the coordinator.

  • Start or extend the pairing mode on the target instance
  • as long as there are at least 30 seconds left on the pairing countdown, delete the selected router device(s) from the source instance
  • watch the pairing window of the target instance The freshly deleted router devices should appear and pair with the new instance. Take note of each device which does not show up automatically. It will require a manual reset at a later time.
  • If the pairing countdown is running out before all router device(s) have paired to the target instance, the pairing countdown should be extended. Note that an extension past 300 s (time from deleting the device from the source instance until the target instance network is closed makes little sense. A device which didnt appear in 5 minutes is unlikely to appear without a manual reset of the device itself.)

Repeat this until all router devices have either been migrated to the target instance or are known to not automatically migrate.

Now go through the EndDevices. Repeat the process, but ensure that the devices are awake before attempting to remove them from the source instance. If a device will not gracefully leave the adapter when it is awake, it is ok to force delete the device. In this case, the device will need to be reset manually anyway. Since the Adapter 3.3.x supports opening the network on a router device, it may be a good idea to select a fitting router device to open the target instance at when trying to move the EndDevices. Also - any EndDevice which does not automatically go into pairing mode should immediately be reset and paired to the target instance.

Once all devices have been removed from the source instance, this instance can be deleted from the host. It is no longer needed.

At this point, time has come to manually reset the router devices which failed this procedure.