Tricks for ZHA&Z2M - thirdreality/LinuxBox GitHub Wiki

Zigbee Software Mode Switching Guide

As everyone has discovered, the Third Reality team provides a quick installation method for zigbee2mqtt in the Linux Installer project. At the same time, we also provide the ability to switch between two different Zigbee software modes: ZHA and Z2M.

1. Zigbee Software Mode Introduction

1.1 ZHA Mode (Zigbee Home Automation)

ZHA mode is Home Assistant's built-in Zigbee integration solution and is the default software mode during installation.

Features:

  • High integration: Directly integrated into Home Assistant without additional services
  • Simple configuration: Can be configured through the Home Assistant interface
  • Low resource usage: No additional MQTT broker required
  • Beginner-friendly: Relatively gentle learning curve

Use Cases:

  • Small to medium Zigbee networks (less than 100 devices)
  • Environments with high system resource requirements
  • Users who want simplified configuration
  • Scenarios primarily using common Zigbee devices
  • Standard Zigbee Home Automation protocol devices

1.2 Z2M Mode (Zigbee2MQTT)

Z2M mode implements Zigbee device management by installing additional zigbee2mqtt services, while also requiring the installation of mosquitto MQTT broker service.

Features:

  • Powerful functionality: Supports more Zigbee devices and advanced features
  • High independence: Can run independently of Home Assistant
  • Flexible configuration: Supports complex Zigbee network configurations
  • Good community support: Active community and rich plugins
  • Better device compatibility: Supports Zigbee devices from more manufacturers
  • Supports custom device configuration and advanced features

Use Cases:

  • Large Zigbee networks (more than 100 devices)
  • Users who need advanced Zigbee functionality
  • Scenarios requiring independent Zigbee network management
  • Complex environments using Zigbee devices from multiple manufacturers
  • Scenarios requiring custom device configuration

2. Switching Methods

Method 1: Using 3R-Installer.app (Recommended)

Step 1: Install 3R-Installer.app

Step 2: Connect LinuxBox to WiFi

Reference link: How to connect LinuxBox to WiFi

Step 3: Switch Zigbee Software Mode

  1. Find the newly added Linuxbox in the 3R-Installer.app interface and click to enter the next page
  2. You can see the "Zigbee Mode" option on the page
  3. Different switching options are displayed based on the current mode:
    • When currently in ZHA mode: displays "Switch to Z2M Mode"
    • When currently in Z2M mode: displays "Switch to ZHA Mode"
  1. Click the switching option, and the system will display a progress dialog for the current switching operation
  1. After waiting for Home Assistant to come back online, Zigbee will work in the new software mode

Important Notes:

  • Please choose the appropriate Zigbee software mode based on actual needs
  • It is not recommended to switch modes frequently, as it may affect device stability

Method 2: Using Command Line Instructions (Advanced Users)

Switch to ZHA Mode

/usr/local/bin/supervisor zigbee zha

Switch to Z2M Mode

/usr/local/bin/supervisor zigbee z2m

Warning: Please ensure you are very familiar with the system and clearly understand the effects and possible results of the commands you execute.

3. Mode Switching Considerations

Pre-switching Preparation

  1. Backup Configuration: It is recommended to backup the current Home Assistant configuration before switching
  2. Device Status: Ensure all Zigbee devices are in normal working condition
  3. Network Stability: Ensure stable network connection to avoid interruption during switching

Post-switching Configuration

  1. Rediscover Devices: After switching, you may need to rediscover and configure Zigbee devices
  2. Check Device Status: Verify that all devices are working normally
  3. Update Automations: If you use Zigbee-related automations, you may need to update the configuration

4. Troubleshooting

Common Issues

1. Devices Cannot Connect After Switching

Solutions:

  • Check if the Zigbee adapter is working properly
  • Restart the Home Assistant service
  • Re-pair devices that cannot connect

2. Switching Process Interrupted

Solutions:

  • Check network connection stability
  • Re-execute the switching command
  • If the problem persists, consider resetting the system

3. Slow Device Response

Solutions:

  • Check if the Zigbee network channel is congested
  • Consider changing the Zigbee channel
  • Optimize device layout to reduce signal interference

Getting Help

If you encounter problems that cannot be resolved, please:

  1. Check Home Assistant logs for detailed error information
  2. Visit the Third Reality official forum for help
  3. Contact the technical support team