Better support for Tuya on-off countdown/timeout

[schauveau]

NOTE: I already filled #22182 about that.

Devices with the on-off cluster are documented in Z2M with the On with timed off feature :

When setting the state to ON, it might be possible to specify an automatic shutoff after a certain amount of time. To do this add an additional property on_time to the payload which is the time in seconds the state should remain on. Additionnaly an off_wait_time property can be added to the payload to specify the cooldown time in seconds when the switch will not answer to other on with timed off commands. Support depend on the switch firmware. Some devices might require both on_time and off_wait_time to work Examples : {"state" : "ON", "on_time": 300}, {"state" : "ON", "on_time": 300, "off_wait_time": 120}.

This is a standard behavior of the on-off cluster described in the Zigbee standard. See sections 3.8.2.3.6 On With Timed Off Command and **3.8.2.4 State Description ** in the ZCL.

However, Tuya devices that support the on-off cluster have a slightly different implementation so the behavior described above does not work as expected. The cluster attributes are the same but with the following differences:

• The OnTime and Off Wait Time fields are in 1/10 seconds in the Zigbee standard but in seconds in Tuya.
• OffWaitTime does not really have any use in Tuya (I think) but the documentation says that it should be set to the same value than OnTime.
• In Tuya, the behavior is a toggle after OnTime seconds. According to the zigbee standard, this is transition from ON to OFF after OnTime 1/10th seconds.

Simply speaking, Tuya on-off cluster implements a delayed toggle (i.e. a countdown). In Z2M, a toggle after 14 seconds can already be obtained with

 {"state" : "ON", "on_time": 1.4 , "off_wait_time": 1.4 }

Notice how the delay of 14 seconds must be divided by 10. This is because Z2M is incorrectly assuming that the OnTime and OffWaitTime fields are in 1/10 seconds.

This is documented for all Tuya standards that support the On/Off cluster in https://developer.tuya.com/en/docs/connect-subdevices-to-gateways/Zigbee_2?id=Kcww7qppbe87m . The links in the page body are all in Chinese but can be changed to English using the 'World' icon at the top of the page (or replace /cn/ by /en/ in the URL.

For example, the Standard for Smart Metering Socket documents the Timer feature as follow:

================================

Direction	Cluster ID	Command/Attribute ID
Client to server	0x0006: On/Off	0x42: On With Timed Off	Payload
Server to client	0x0006: On/Off	0x4001: OnTime 0x4002: OffWaitTime	0 to 43200

Format of payload: On/off Control: 0x00. On time and Off Wait Time must be set to the same value. Example: To send a command of a local countdown for 60s, the payload contains the following settings:

• On/off Control: 0x00
• On Time: 0x003c
• Off Wait Time: 0x003c

================================

A few remarks:

• 0x003c = 60 so the time is expressed in seconds and not in 1/10s
• OffWaitTime should be equal to OnTime. I did not follow that rule in my external converter but it seems to work fine at least for now.
• The server is supposed to send OnTime and OffWaitTime back to the client probably to inform it how much time is remaining. Z2M should probably publish those attributes if they are effectively available.
• why 0 to 43200 ? because 43200s = 12 * 3600s = 12 hours. The full 16bits range 0-0xFFFF may not be allowed. Some tests are needed.
• It is never explicitly stated that the countdown action is a 'toggle' but that makes sense as long as we ignore the names OnTime and OffWaitTime
  that were obviously borrowed from the non-tuya standard behavior.

The Standard for Smart Switch is slightly different but the idea remains the same:

Countdown
    - The countdown function is implemented with the 0x42 command of 
    the Zigbee on/off cluster.
- After the countdown command is received, the device starts to count down. 
The count value is decreased by 1 every second. The countdown data is 
written to the OnTime and OffWaitTime attributes.

- After the count value becomes 0, the bits are reversed and the switch status
and values of OnTime and Off Wait Time are reported to the gateway.

[avbdr]

interesting. I were researching with like a week ago and my tuya switches behave differently. When the switch is off, state: on, on_time: will turn it on after on_time timeout. It doesnt turn the light on when receives a command. weird

[avbdr]

i can confirm that for tuya this /10 can be removed since it seems tuya is not following the spec

[schauveau]

Indeed. The command is not supposed to toggle or turn on the switch immediately with the Tuya behavior. This is just a delayed toggle. The syntax { "state" : "on", "on_time": VALUE } makes sense for the Zigbee standard but not for Tuya since that has nothing to with "state" : on.

Something like { "state" : "toggle", "on_time": VALUE } , { "state" : "toggle", "countdown": VALUE } or { "toggle_with_delay": VALUE } would be more appropriate.

[schauveau]

Also, the values of OnTime and OffWaitTime are supposed to be reported by the tuya device. It could be interesting to have them published as attributes.

[avbdr]

@schauveau the main benefit of on_time is to avoid local scheduling and sending second OFF request via the network. if you want to turn on something for 20 minutes, you send ON,on_time: 20 and done. In timeout_toggle, you would have still send extra zb command over the network.
Id rather use a scheduler and send OFF command when needed. :(

Wonder if tuya behavior can be changed to the normal one

[schauveau]

It is of course always possible to use a scheduler to send the ON or OFF command after a delay but it is probably safer to let the device handle it automatically when possible because there is always a risk that the scheduler will go offline. I agree that it would be safer to send both the on/off and the timeout_toggle in the same zigbee message.

Anyways, that behavior is likely the only one that is available on those TUYA devices so it would be nice if it was natively supported by Z2M. This is a small change that would benefit hundreds of TUYA devices.

[schauveau]

I forgot to mention that an active timeout toggle can be cancelled by either setting state or by setting on_time to 0.

Here is a converter that adds a command { "timeout_toggle" : DELAY } to the WHD02 smart switch. The real stuff should of course be done within tuya.modernExtend.tuyaOnOff( ).

const fz = require('zigbee-herdsman-converters/converters/fromZigbee');
const tz = require('zigbee-herdsman-converters/converters/toZigbee');
const exposes = require('zigbee-herdsman-converters/lib/exposes');
const tuya = require('zigbee-herdsman-converters/lib/tuya');
const utils = require('zigbee-herdsman-converters/lib/utils');
const e = exposes.presets;
const ea = exposes.access;


//
//  /set { timeout_toggle : delay }
//
//    Toggle the state after 'delay' from 1 to 43200 seconds (12 hours).
//
//    Use 0 to cancel a currently running timeout_toggle. 
//
//    The delay is rounded to the nearest integer so 0.3 is actually 0.
//
//    The pending toggle delay can also be cancelled by setting `state`.
//
const tuya_timeout_toggle = {
    key: ['timeout_toggle'],
    convertSet: async (entity, key, value, meta) => {
        utils.assertNumber(value);
        const errmsg = 'The toggle delay must be a number of seconds between 1 and 65534' ;
        if (typeof value !== 'number' ) {
            throw Error(errmsg);
        } 
        
        const delay = Math.round(value)
        // Might work up to 0xFFFF seconds but the Tuya says 43200 (so 12 hours) 
        if ( delay < 0 || delay > 12*3600 ) {
            throw Error(errmsg);
        }

        // offwaittime  is probably not used but the tuda documentation states
        // that ontime and offwaittime should be set to the same value. 
        const payload = {ctrlbits: 0, ontime: delay, offwaittime: delay};
        await entity.command('genOnOff', 'onWithTimedOff', payload, utils.getOptions(meta.mapped, entity));
        return {}
    }
};


const definition =
    {
        fingerprint: [{ modelID: 'TS0001', manufacturerName: '_TZ3000_hktqahrq' }, { manufacturerName: '_TZ3000_hktqahrq' },
            { manufacturerName: '_TZ3000_q6a3tepg' }, { modelID: 'TS000F', manufacturerName: '_TZ3000_m9af2l6g' },
            { modelID: 'TS000F', manufacturerName: '_TZ3000_mx3vgyea' },
            { modelID: 'TS000F', manufacturerName: '_TZ3000_skueekg3' },
            { modelID: 'TS000F', manufacturerName: '_TZ3000_dlhhrhs8' },
            { modelID: 'TS000F', manufacturerName: '_TZ3000_fdxihpp7' },
            { modelID: 'TS0001', manufacturerName: '_TZ3000_skueekg3' },
            { modelID: 'TS0001', manufacturerName: '_TZ3000_npzfdcof' },
            { modelID: 'TS0001', manufacturerName: '_TZ3000_5ng23zjs' },
            { modelID: 'TS0001', manufacturerName: '_TZ3000_rmjr4ufz' },
            { modelID: 'TS0001', manufacturerName: '_TZ3000_v7gnj3ad' },
            { modelID: 'TS0001', manufacturerName: '_TZ3000_3a9beq8a' },
            { modelID: 'TS0001', manufacturerName: '_TZ3000_ark8nv4y' },
            { modelID: 'TS0001', manufacturerName: '_TZ3000_mx3vgyea' },
            { modelID: 'TS0001', manufacturerName: '_TZ3000_fdxihpp7' },
            { modelID: 'TS0001', manufacturerName: '_TZ3000_qsp2pwtf' },
            { modelID: 'TS0001', manufacturerName: '_TZ3000_kycczpw8' },
            { modelID: 'TS0001', manufacturerName: '_TZ3000_46t1rvdu' }],
        model: 'WHD02',
        vendor: 'TuYa',
        description: 'Wall switch module',
        toZigbee: [ tuya_timeout_toggle  ], 
        extend: [tuya.modernExtend.tuyaOnOff({ switchType: true })],
        configure: async (device, coordinatorEndpoint, logger) => {
            await tuya.configureMagicPacket(device, coordinatorEndpoint, logger);
            const endpoint = device.getEndpoint(1);
            await reporting.bind(endpoint, coordinatorEndpoint, ['genOnOff']);
            await reporting.onOff(endpoint);
        },
    } ;
    
module.exports = definition;

[schauveau]

Following @avbdr remark, I modified the converter to allow both state and timeout_toggle in the same MQTT command. However, two zigbee commands are still necessary.

CORRECTION: The state value was not properly converted to lower case in my initial post. Should work better now.

 //
//  /set { "state":"on|off|toggle", "timeout_toggle": DELAY }
//
//  Set the state and toggle it after the specified DELAY in seconds.
//
//  Both new_state and timeout_toggle are optional.
//
//  The DELAY can be an integer between 1 and 43200 (12 hours) or 0
//  to cancel
// 
//  Setting a new state will also cancel any ongoing timeout.
//
//  Examples:
//      
//    - turn on without timeout toggle 
//
//       /set { "state":"on" }
//     or 
//       /set { "state":"on" , "timeout_toggle": 0 }
//
//    - turn off and toggle after 10s  
//
//       /set { "state":"off", "timeout_toggle": 10 }
//
//    - toggle now and again after 5s
//        
//       /set { "state":"toggle", "timeout_toggle": 5 }
//
//    - keep current state and toggle after 5s
//
//       /set { "timeout_toggle": 5 }
// 
//    - cancel an ongoing timeout toggle 
//
//       /set { "timeout_toggle": 0 }
//     
const tuya_onoff_with_timeout_toggle = {
    key: ['state', 'timeout_toggle'],
    convertSet: async (entity, key, value, meta) => {
        // If I understand correctly, this is called ONCE when any of the
        // listed keys is present.
        // Note: `key` and `value` seem to be the first ones given
        //       in the MQTT payload but that does not necessarily make sense
        //       since the members of a JSON object are supposed to be unordered.
        //       Simply speaking: Do not use key and value. 
        let new_state = meta.message.hasOwnProperty('state') ? meta.message.state : undefined ;
        const timeout_toggle = meta.message.hasOwnProperty('timeout_toggle') ? meta.message.timeout_toggle : undefined ;
        let result = {};

        // Perform all consistancy checks first to insure that either all or none of the
        // requested commands are sent.
        
        if ( timeout_toggle !== undefined ) {
            // Might work up to 0xFFFF seconds but the Tuya documentation says 43200 (so 12 hours).
            // Tests needed
            if ( !Number.isInteger(timeout_toggle) || timeout_toggle < 0 || timeout_toggle > 12*3600 ) {
                throw Error('timeout_toggle must be an integer between 1 and 43200 (12 hours) or 0 to cancel' );
            }
        }
        if ( new_state !== undefined ) {
            new_state = utils.isString(new_state) ? new_state.toLowerCase() : null;
            utils.validateValue(new_state, ['toggle', 'off', 'on']);
        }
        
        // Now, send the requested commands in the proper order: 'on/off/toggle' and then 'onWithTimedOff'.
        if (new_state !== undefined) {
            await entity.command('genOnOff', new_state, {}, utils.getOptions(meta.mapped, entity));
            if (new_state === 'toggle') {
                const currentState = meta.state[`state${meta.endpoint_name ? `_${meta.endpoint_name}` : ''}`];
                result = currentState ? {state: {state: currentState === 'OFF' ? 'ON' : 'OFF'}} : {};
            } else {
                result = {state: {state: new_state.toUpperCase()}};
            }
        }
        if ( timeout_toggle !== undefined ) {
            const payload = {ctrlbits: 0, ontime:timeout_toggle , offwaittime:timeout_toggle };
            await entity.command('genOnOff', 'onWithTimedOff', payload, utils.getOptions(meta.mapped, entity));
        }    

        return result ;

    }
};

[schauveau]

And here is a converter to publish theonTime attribute as timeout_toggle.
It also adds an action timeout_toggle when timeout_toggle is modified to a non-zero value and no_timeout_toggle when zero.

The timeout_toggle (i.e. onTime) attribute is reported by the device when it is assigned or when it reaches 0.
That behavior can be be changed by changing the reporting values for attribute onTime in cluster onOff.

For example, to update timeout_toggle every 5 seconds while a timeout is ongoing and 120 seconds otherwise do

mosquitto_pub -t zigbee2mqtt/bridge/request/device/configure_reporting -m '{"id":"plug1","cluster":"genOnOff","attribute":"onTime","minimum_report_interval":5,"maximum_report_interval":120,"reportable_change":0}'

There is currently no reporting.onTime() function to set some reasonable defaults. That should probably be added.
I also noticed that some tuya devices (e.g. TS011F_plug_1) lack reporting.onOff() in their configure.

[ESP4Ever]

Hi!

I tried to use the countdown feature in the HA automation to turn off the light activated by a presence sensor and it works but the problem is when the light is toggled by countdown, its status is not updated in HA

[schauveau]

I am successfully using countdown on multiple plugs and dry switches.

First you need to figure out if the on/off status is properly reported in Z2M for example using the Z2M web interface? A custom reporting rule could solve the problem.

If its works fine in Z2M then the problem is likely in HA. Are you you sure that your widget is properly reacting to changes it did not initiate?

[ESP4Ever]

Here is:

Zigbee Model TS0001
Zigbee Manufacturer _TZ3000_4rbqgcuv
Description 1 gang switch module
Support status Supported
IEEE Address xxxxx
Network address xxxxxx
Manufacturer AVATTO
Model ZWSM16-1-Zigbee

I tested countdown via HA and directly from z2m frontend - result is the same

[schauveau]

Good. That device appears to be using a countdown implementation corresponding to what was described in this discussion (i.e. onOffCountdown: true passed to tuya.modernExtend.tuyaOnOff at https://github.com/Koenkk/zigbee-herdsman-converters/blob/973f11b01c5b5987f51a4a749b580744295412cf/src/devices/tuya.ts#L4007 )

My own plug devices are mostly TS011F_plug_1 so a different device but using the same implementation for countdown. https://github.com/Koenkk/zigbee-herdsman-converters/blob/973f11b01c5b5987f51a4a749b580744295412cf/src/devices/tuya.ts#L5549

I notice that this is also a AVATTO device so your problem may be specific to that manufacturer.

I am wondering if that device is really implementing the Tuya OnWithTimedOff or if this a standard OnWithTimedOff. If this is the later, I would expect the following:

1. In the standard zigbee implementation, the delay is in 1/10s so if you specify 60 then the action shall occur after only 6 seconds.
2. In standard zigbee implementation, the command cannot be used to turn on the device. As indicated by the name, this supposed to be a "Turn on" followed by a "Timed turn off".

Do you see anything like that here?

[schauveau]

I forgot to mention that there are refresh issues in the Exposes pane of the Z2M web interface. This is not systematic but the values are not always properly updated to reflect the actual state. The State pane is better.

[ESP4Ever]

The command can be used in both directions for delayed on or delayed off, also it is appear as a separate controller at the HA/z2m frontend

[schauveau]

For me, that looks more and more like an Avatto problem.

Try to add an explicit reporting for the onOff attribute. It may be required for Avatto devices. This is more likely to work on the switch than on the dimmers since they are using Tuya datapoints.

My only remaining advice is to create a new discussion about Countdown behavior of Avatto devices. That may attract other people with the same device and hopefully some solutions.