Zigbee device plugin mechanism with commands ZbLoad, ZbUnload and ZbLoadDump

[s-hadinger]

Description

This is a major new feature for Zigbee2Tasmota.

From the start, Z2T design was to stick to a low-level view and provide higher level (named) attributes only for a limited set of mostly seen attributes. This raised difficulties and frustration for users with specific devices that use rare attributes, or devices that use non-standard attributes (like Tuya zigbee devices).

We are now providing a Zigbee Device plugin mechanisms, using simple text files. These files specify mapping on a per-device type basis. The goal is to fill most of the gap with Zigbee2MQTT (provided that you write the device plugin files). The lightweight nature of plugins permits to load only the plugins required by the devices used, and does not require a sowftare update for new devices.

How does it works?

You simply copy device plugin files (externsion *.zb) in the file system and they are automatically loaded at start.

You can dynamically load new files with ZbLoad <file>.zb or unload definitions with ZbUnload <file>.zb. When you reload a file with the same name, it is first unloaded.

At Zigbee start, all files with *.zb suffix are loaded into memory. Be careful of not saturating memory, especially on ESP8266.

Zigbee devide plugin format

Zigbee device plugin have the following format:

• starts with #Z2Tv1 on the first line
  • # is a marker for comments, and everything from # to end of line is ignored
  • rest of the file is of form device matcher followed by attribute definitions or attribute synonyms

device matchers

• composed of one or more lines defining the modelId and manufacturerId. If a field is empty, it matches all values
• :<modelId>,<manufacturerId>
• example: :TS0601,_TZE200_sh1btabb for GiEX water valve

attribute matcher specifies a cluster/attribute/type tuple and matches an attribute name

• <cluster 4 hex>/<attribute 4 hex> or <cluster 4 hex>/attribute 4 hex>%<type 2 hex>
• Ex: EF00/0365,IrrigationStartTime (Tuya cluster EF00 does not need an explicit type)
• Ex: 0006/4001%bool,OnTime

attribute synonyms specifies that a received attribute is a synonym for another attribute

• <cluster 4 hex>/<attribute 4 hex>=<new_cluster 4 hex>/<new_attribute 4 hex>,<multiplier>
• Ex: EF00/026C=0001/0021,2 converts any EFOO/026C attribute received to 0001/0021 (BatteryPercentage) and multiplies by 2 to convert to ZCL standard.

Multiplier is 8 bit int (-128..127). If 0 or 1, the value is unchanged. Otherwize the value is converted to float and is multiplied by multiplier if positive, or divided by -multiplier if negative.

I.e. multiplier=10 means multiply by 10, multiplier=-5 means divide by 5

Also included

Refactoring of attributes matching engine to allow plugins and device-specific mappings.

Coming next

• more device definition files
• support for manufacturer codes
• support for Tuya time sync
• support for custom Zigbee commands

Checklist:

• The pull request is done against the latest development branch
• Only relevant files were touched
• Only one feature/fix was added per PR and the code change compiles without warnings
• The code change is tested and works with Tasmota core ESP8266 V.2.7.4.9
• The code change is tested and works with Tasmota core ESP32 V.2.0.4.1
• I accept the CLA.

NOTE: The code change must pass CI tests. Your PR cannot be merged unless tests pass

[barbudor]

Wouah !!! 🤩

[jbarta63]

Good day,
I would like to solve a problem with a TUYA single-channel controller.

when pressed it prints:

tele/tasmota_28F3DE/_"TUYA_Switch"/SENSOR = {"ZbReceived":{"0x7A2F":{"Device":"0x7A2F","Name":" "TUYA Switch"","0006!FD":" 00","LidlPower":0,"Endpoint":1,"LinkQuality":79}}}
14:35:20.137 ZIG: {"ZbEZSPReceived":"340000F2"}

For the cluster "0006!FD":" 00" is the FD value, but I would need "0006!01":" 00" to turn on the light.

Is it possible to change it using the Zigbee device plugin, or could someone tell me what the file should look like?

thank you in advance Jan

[s-hadinger]

No it's not possible directly. Is your coordinator based on Esp32?

[jbarta63]

Yes, this is SonOff Zigbee-WiFi gateway with ESP processor and Tasmota Zigbee: EZSP v6.7.8.0.

Jan

[sfromis]

But is it ESP32 instead of ESP8266?

[jbarta63]

Yes, this is an ESP8266

Jan

[s-hadinger]

In that case I don't have any solution. If you use a ZBBridgePro, you can do custom Berry code for this kind of transformation.

What you can do is handle these message in a MQTT coordinator (if you have any). But I would rather suggest to move to ESP32.

[jbarta63]

Of course, I can buy ZBBridgePro if such cases can be solved with it. I really like working with Zigbee2Tasomota.

In the best case, of course, I can process it via MQTT, but I prefer to solve the basic relationships between individual elements at the Zigbee level.

I will be very happy for such a solution.

best regards Jan