Feature: per-device/per-model option to ignore leave events

[chrischris616]

Summary

Request for a per-device or per-model option to ignore device_leave events in zigbee-herdsman, preventing removeFromDatabase() from being called for configured devices.

Problem

Tuya TS0505B (Moes ZB-TDD6-RCW-4) ceiling spots send spurious leave events when power is restored via a mains relay (wall switch). This is a firmware quirk — the devices never actually leave the Zigbee network. They continue to be physically present and communicating.

When herdsman processes the leave event, it calls removeFromDatabase(), which:

1. Removes the device from shepherd.db
2. Removes the device from herdsman's in-memory device list
3. All subsequent messages from the device are silently dropped (controller.js:775: "Data is from unknown device, skipping...")
4. Commands to the device fail because herdsman doesn't know it anymore

The device is still on the Zigbee network. If we manually restore the device entry in shepherd.db and restart, the device is immediately controllable without re-pairing (first command takes ~11s for route discovery, then normal 50ms latency).

Use case

Smart ceiling spots (37 Tuya TS0505B) installed behind HomeMatic mains relays (wall switches). Toggling the wall switch turns all spots on/off — this is the normal, intended operation. Every power cycle risks triggering phantom leave events that permanently remove devices from the database.

This is a common installation scenario for smart bulbs. The Zigbee specification's leave mechanism is intended for devices voluntarily leaving the network, not for firmware bugs during power-on.

Proposed solution

A per-device or per-model callback/option that allows the consuming application (e.g., ioBroker.zigbee adapter) to tell herdsman to ignore leave events for specific devices.

Working implementation

We have a working patch in controller.js that has been running in production since 2026-02-22 with 37 devices and zero issues:

// In Controller class:

_shouldIgnoreLeave(device) {
    try {
        const fs = require('fs');
        const path = require('path');
        const overridesPath = path.join(this.options.databasePath, 'LocalOverrides.json');
        
        if (!fs.existsSync(overridesPath)) return false;
        
        const overrides = JSON.parse(fs.readFileSync(overridesPath, 'utf8'));
        const ieeeShort = device.ieeeAddr.replace('0x', '');
        
        // Check by device ID
        const byId = overrides.by_id?.[ieeeShort];
        if (byId?.disable_leave_delete || byId?.options?.disable_leave_delete) return true;
        
        // Check by model
        const modelId = device.modelID;
        if (modelId) {
            const byModel = overrides.by_model?.[modelId];
            if (byModel?.disable_leave_delete || byModel?.options?.disable_leave_delete) return true;
        }
        
        return false;
    } catch (e) {
        return false;
    }
}

Applied in the onDeviceLeave handler (around line 541):

async onDeviceLeave(payload) {
    const device = model_1.Device.byIeeeAddr(payload.ieeeAddr);
    
    if (device && this._shouldIgnoreLeave(device)) {
        logger_1.logger.info(`Ignoring leave event for ${device.ieeeAddr} (${device.modelID}) — ignore_leave is configured`);
        return;  // Skip removeFromDatabase()
    }
    
    // ... existing leave handling ...
}

Cleaner API approach

Instead of reading config files directly, herdsman could expose a hook:

// Option 1: Callback
const controller = new Controller({
    shouldIgnoreLeave: (device) => {
        // Application decides per device
        return configuredModels.includes(device.modelID);
    }
});

// Option 2: Configuration list
const controller = new Controller({
    ignoreLeaveModels: ['TS0505B'],
    ignoreLeaveDevices: ['0xa4c138...']
});

Evidence

• 37 Tuya TS0505B devices monitored for 5+ days
• 30+ leave events observed from normal wall switch operation (single relay toggles)
• Devices send commandActiveStatusReport (LQI 91-156) seconds before the leave — proving they are healthy
• After manual shepherd.db restore: immediately controllable, no re-pairing needed
• With our herdsman-level patch: zero device losses since Feb 22, all communication uninterrupted
• Full debug logs and test results documented in ioBroker/ioBroker.zigbee#2748

About security

The ioBroker.zigbee adapter maintainer (@asgothian) raised concerns about "breaking Zigbee network security." We believe this is not applicable here because:

1. This is an opt-in option, not a default behavior change
2. It targets hardwired ceiling fixtures that cannot be physically removed
3. The leave events are not legitimate — the devices are not voluntarily leaving
4. The option would be configured per device or per model, not globally
5. A device that genuinely needs to leave (e.g., factory reset for re-pairing to a different network) would still work via the normal pairing process

Environment

• zigbee-herdsman 9.0.4
• Coordinator: ZStack3x0, Firmware 20250321 (CC2652P)
• 37x Tuya TS0505B (_TZ3210_b8jdosxo) / Moes ZB-TDD6-RCW-4
• All devices are Routers (mains-powered ceiling spots)

[asgothian]

Three quick comments from my side:

• i am not actively supporting / blocking this request. I am indifferent to it. I can and will add code to support ZH functionality to the ioBroker adapter if needed, though.
• reading the LocalOverrides.json from any software other than the ioBroker.zigbee adapter is strongly discouraged. This is an internal file which may have its internal formatting / structure change without notice. This makes the proposed solution not viable in my eyes.
• I consider the cleaner 'API' approach to be not clean. There are a number of questions attached to this approach, including but not limited to:
  -- data being set when the controller is instanced, before it is known which devices exist
  -- data needing to be updated if a device join / leaves the network
  -- additional callback functionality for a rare case, breaking the zigbee network integrity should the client application choose to do so.

I will read here but not be an active participant in this discussion.

A.

[chrischris616]

Update: The ioBroker.zigbee adapter maintainer has reviewed this issue and confirmed that this needs to be solved at the herdsman level. The adapter-side issues (#2748, #2750) have been closed on the adapter side — the adapter cannot work around the fact that herdsman removes the device from shepherd.db and its in-memory database on every device_leave event.

Our local patch (_shouldIgnoreLeave() in controller.js:541-554) has been running in production with 37 Tuya TS0505B spots since Feb 22 with no issues. Happy to provide any additional logs or testing if needed.

[Nerivec]

If the device is triggering a leave but not actually rejoining (device announce / rejoin) after a power cycle, I'd consider this device broken.
A device that leaves must be removed from the application simply because the other devices on the network would do the same thing internally. It might "somewhat keep working" by ignoring the leave, but it likely is making a huge mess in the network's tables.
Definitely a security issue as well, it's literally bypassing all security measures...

[chrischris616]

@Nerivec Thanks for looking at this. I'd like to address your points because I think there's a misunderstanding about what's happening at the network level.

"Device broken" / "not rejoining"

The devices do rejoin. They send device_announce after every power cycle. The problem is that herdsman processes the Leave_Indication first and calls removeFromDatabase(), which removes the device from shepherd.db and the in-memory device list. By the time the device_announce arrives seconds later, herdsman drops it because the device is already gone from its database.

If we restore the shepherd.db entry (without re-pairing), the device is immediately controllable — first command takes ~10s for route discovery, then normal 50-280ms latency. This proves the device never actually left the Zigbee network. The network key, group memberships, and bindings are all intact.

"Other devices would do the same thing internally"

End devices (which these spots are) don't maintain neighbor or routing tables for other end devices. The coordinator's routing tables update naturally through normal Zigbee network maintenance. A spurious Leave_Indication processed at the application layer in herdsman has no effect on the actual Zigbee network topology — the device is still associated with the coordinator and holds the network key.

"Huge mess in the network's tables"

We've been running 37 Tuya TS0505B spots with ignore_leave in production since Feb 22 (over 48 hours, multiple power cycles via wall switches). Zero network issues. All spots respond to group commands, individual commands, and report their state. No routing problems, no ghost entries, no missed messages. The network is healthy.

"Security issue / bypassing security measures"

removeFromDatabase() is an application-level operation — it removes a JSON entry from shepherd.db. It is not a Zigbee security mechanism. The actual Zigbee network security is handled by the trust center policy and the network key, which are not affected by whether herdsman tracks a device in its local database or not.

A device that sends a spurious leave but stays on the network (retaining its network key) is not a security risk — it's a firmware bug. Ignoring the leave at the herdsman level simply prevents the application from losing track of a device that is still physically present and communicating.

These are ceiling spots hardwired behind mains relays — they cannot be physically removed. Toggling the wall switch is the normal, intended way to operate them. This is a common installation scenario for smart bulbs.

What we're asking for

A per-device or per-model option (not a global setting) that lets the consuming application tell herdsman: "I know this device sends spurious leaves, don't remove it." This is opt-in, explicit, and doesn't change default behavior. It gives applications the ability to handle known firmware quirks without losing device state.

Happy to provide logs, packet captures, or any other evidence that would be helpful.

[Nerivec]

The devices do rejoin. [...]

Sounds like a broken TC rejoin.

Most of this is making the incorrect assumption that the leave affects only ZH, it does not, the network (routers, tables) will react to it internally as well. Also, the application is expected to behave as the Zigbee specification intended, especially regarding security-related operations.
My previous comment stands.

[chrischris616]

@Nerivec

Sounds like a broken TC rejoin.

It's not a TC rejoin issue — the device never actually leaves the network. It retains its network key, responds to commands, and reports state. The Leave_Indication is sent by the firmware during power-on initialization, before the device has even finished booting. This is a well-known Tuya firmware bug, not a protocol violation by the coordinator.

the network (routers, tables) will react to it internally as well

End devices don't participate in routing. Routers update their neighbor tables through normal network maintenance (link status, route discovery). A spurious Leave_Indication from an end device that never actually left does not corrupt any routing state — the device is still associated, still holds the network key, and still communicates normally. We have 37 of these devices running with the patch for 3+ days with zero network issues.

Independent confirmation: tuyaZigbee custom firmware project

The doctor64/tuyaZigbee project exists specifically because of known firmware bugs in Tuya's Zigbee modules (TLSR8258 / ZT3L). They provide replacement firmware for TS0501B, TS0504B, and various switches. The TS0505B is listed but marked "Not started."

This confirms that the Tuya firmware behavior is a recognized problem in the community — serious enough that people are writing replacement firmware from scratch. But until custom firmware covers the TS0505B, users need an application-level workaround for devices that are already deployed.

What we're proposing is conservative

We're not asking herdsman to ignore all leaves globally or to break Zigbee compliance. We're asking for a per-device opt-in flag that lets the consuming application say "I know this specific device has buggy firmware, don't delete it on leave." The default behavior stays unchanged. This is exactly the kind of device-specific quirk handling that already exists in zigbee-herdsman-converters for dozens of Tuya models.

[Nerivec]

You are misreading what I am saying.

Per Zigbee spec:

When the local device receives a NLME-LEAVE.indication with Rejoin set to FALSE it SHALL remove any persis-
tent data within the stack related to the leaving device.

[chrischris616]

@Nerivec I understand the spec requirement. But consider this real-world scenario:

A household with Zigbee smart bulbs installed in ceiling fixtures, controlled by standard wall switches. A small child plays with the light switch — rapidly toggling it on and off, as children do. The Tuya firmware interprets this as a factory reset sequence (3x power cycle within 0.7s) and enters pairing mode, sending a device_leave.

This is not an exotic edge case — it's an everyday situation in any household with children and wall switches. You cannot childproof every light switch, and you cannot expect users to never power-cycle their Zigbee bulbs.

The result without a workaround: the device is removed from herdsman's database, becomes uncontrollable, and requires manual intervention (re-pairing or shepherd.db restore) — even though the device never actually left the network and returns to normal operation after the pairing timeout.

We're not asking herdsman to violate the spec by default. We're asking for an opt-in, per-device flag that lets the application handle a known firmware bug in one of the most widely deployed Zigbee chipsets (Tuya TLSR8258). The default behavior stays spec-compliant.

The Tuya firmware bug is well-documented — the tuyaZigbee custom firmware project exists specifically because of these issues. But until custom firmware is available for the TS0505B, deployed devices need an application-level workaround.