top of page

Quick Start Guide for Connecting MG21 USB to Home Assistant

Home Assistant

This quick-start guide provides basic information on configuring, building and installing MG21 USB as a Zigbee Gateway to make it work with the Home Assistant platform.

​

Prerequisites

Steps to connect USB Dongle to Home Assistant

  1. Flash new bootloader and NCP firmware to USB dongle - The bootloader should be flashed first, and then you can choose ncp-uart-hw or ncp-uart-sw uses (recommend ncp-uart-hw for best performance and reliability).

  2. Flash firmware steps:
    (1) Connect the MG21 USB dongle to a PC (which has USBStickLoader.exe).
    (2) Open USBStickLoader.exe
    (3) Click on the Find button to scan all USBStick port
    (4) Choose Serial Port
    (5) Click on the Browse button to find the .gbl file for flashing.
    (6) Finally click on the Flash button to flash new firmware.

Programming the dongle

Figure 1: Flash firmware guides

Integrate the USB Dongle into Home Assistant

  • Connect MG21USB Dongle to your host machine where Home Assistant is installed.

  • Restart Home Assistant

  • Open Home Assistant => Settings => Devices & Services.

  • Use the plus button in the bottom right to add a new integration called ZHA (Zigbee Home Automation).

  • In the popup, pick one to which your USB dongle is connected, then "Submit" (shown like the picture below)

step 6

Figure 2: Choose device path

  • The integration will try to detect radio type automatically. If unsuccessful, you will get a new pop-up asking for a radio type. In the pop-up, choose EZSP and Submit.

  • You will get a new pop-up window asking for port settings specific to this radio type. If your USB dongle has been flashed with the ncp-uart-hw image, please choose port speed 115200 and check the hardware radio button. For the dongle that has been loaded with ncp-uart-sw, please set the port speed as 57600 and check the software radio button.

step 3

Figure 3: Select protocol

step 4

Figure 4: Serial Port Settings with ncp-uart-hw firmware

step 5

Figure 5: Serial Port Settings with ncp-uart-sw firmware

  • Press Submit. The success dialog will appear, or an error will be displayed in the popup. An error is likely if Home Assistant can’t access the USB device, or your device is not up to date. Please refer to Troubleshooting below for more information.

step 2

Figure 6: Configuration success

  •  Then click on Restore an automatic backup if you already have a backup network file or Erase network settings then form a new network.

Troubleshooting

During the integration USB dongle to the Home Assistant platform, you can turn on the log to see more details about the configuration process by enabling them on configuration.yaml file:


logger:
default: info
logs:
homeassistant.core: debug
homeassistant.components.zha: debug
bellows.zigbee.application: debug
bellows.ezsp: debug
zigpy: debug
zigpy_deconz.zigbee.application: debug
zigpy_deconz.api: debug
zigpy_xbee.zigbee.application: debug
zigpy_xbee.api: debug
zigpy_zigate: debug
zigpy_znp: debug
zhaquirks: debug

​

If you see the log issue related to serial port as bellow:

step 1

Figure 7: Troubleshooting

  • Please check the port permission and try with this command:
    sudo usermod -a -G dialout $USER

bottom of page