Zigbee2MQTT 2.0.0 Update: Key Changes and Common Problems

With the release of Zigbee2MQTT 2.0.0, many users are excited to take advantage of its new features. However, as with any major update, this version comes with significant changes that can cause disruptions if you’re not prepared. In this guide, I’ll explain everything you need to know about Zigbee2MQTT 2.0.0: the key changes, how to update safely, and common problems with solutions.

Key Changes in Zigbee2MQTT 2.0.0

Zigbee2MQTT 2.0.0 introduces several improvements and removes legacy functionalities that have been deprecated for years. For many of us who have been using Zigbee2MQTT for a long time, this update may require configuration adjustments to avoid compatibility issues. Here are the main changes:

1. Improved Adapter Detection
   While this is a great feature, it can sometimes result in a “USB adapter discovery error (No valid USB adapter found)”. This happens if your configuration is outdated or your Zigbee dongle firmware is incompatible. I’ll cover how to address this later.
2. Deprecation of Legacy APIs and Configurations
   Features like legacy API support, availability payloads, and certain MQTT topics have been removed. If you’re using these, your configuration will need to be updated.
3. Changes for Home Assistant Integration
   New standards have been introduced for device attributes, triggers, and entities. For example, all legacy action sensors have been disabled by default.
4. Automatic Removal of Obsolete Configurations
   When you first start Zigbee2MQTT 2.0.0, it will clean up deprecated settings. To see what was removed, check the migration-1-to-2.log file in your data directory.

How to Update to Zigbee2MQTT 2.0.0

Updating to Zigbee2MQTT 2.0.0 can seem intimidating, but by following these steps, you’ll be up and running in no time:

1. Backup Your Current Setup
   Before you begin, make a full backup of your configuration.yaml file and any other important files. Trust me, this step can save you a lot of headaches if something goes wrong.
2. Prepare Your Configuration
   To avoid most issues, ensure your configuration.yaml file has the following:

advanced:
  homeassistant_legacy_entity_attributes: false
  homeassistant_legacy_triggers: false
  legacy_api: false
  legacy_availability_payload: false
device_options:
  legacy: false

These settings disable deprecated features and align your setup with the new version.

Perform the Update

Update Zigbee2MQTT using your usual method. If you’re using Docker, the commands are:

docker pull koenkk/zigbee2mqtt
docker restart zigbee2mqtt

1. For other installations, refer to the official update guide.
2. Check for Configuration Changes
   After updating, review the migration-1-to-2.log file to see what has changed. This log will help you identify any settings that need to be adjusted manually.
3. Test Your Devices
   Once everything is updated, test your devices and automations to ensure they’re working as expected.

Common Problems and Solutions

Despite careful preparation, you might encounter some issues after updating. Here are the most common problems and how to solve them:

1. USB Adapter Discovery Error

This is one of the most frequently reported issues. If you see an error like “No valid USB adapter found”, double-check that your serial settings in configuration.yaml are correct:

serial:
  port: /dev/serial/by-id/your-adapter-id
  adapter: ember

To find the correct adapter path, use the command:

ls /dev/serial/by-id/

2. MQTT Connection Issues

Make sure your MQTT broker is configured correctly, and the homeassistant/status topic is set as the birth message in Home Assistant. Reconfigure MQTT in Home Assistant if necessary.

3. Missing or Disabled Entities in Home Assistant

If some entities are missing, check whether legacy triggers or attributes are disabled in your configuration. Use exposes for external converters instead of homeassistant attributes.

4. Devices Not Responding

Ensure your devices are powered and within range of the Zigbee coordinator. Logs can also provide detailed error messages to help diagnose the problem.

5. Updating Your Zigbee Dongle Firmware

If all else fails, your Zigbee dongle firmware might need an update. The new adapter detection in Zigbee2MQTT 2.0.0 may not be compatible with older firmware versions. Look up the firmware update process for your specific dongle model and follow it carefully. Firmware updates can resolve many compatibility issues.

Conclusion

Upgrading to Zigbee2MQTT 2.0.0 is an essential step to stay current with the latest features and improvements. While the process may require some effort, the results are worth it. Follow this guide to prepare your setup, update safely, and troubleshoot any problems. And remember, updating your dongle firmware could be the key to resolving persistent issues.

Follow me on YouTube