OTA update not possible for ZG-303Z in ZHA?

[malocycling]

I recently purchased some ZG-303Z soil moisture sensors and discovered this nice custom firmware project.
In device info however I do not see any information in regards to firmware. Consequently I don't see any OTA options.
OTA updates are enabled in my configuration and firmware file '1286-0203-20973001-ZG303Zz_v0130.zigbee' is placed in the zigpy_ota folder
Is there anything I can do to make OTA work or do I need to run the update through the UART flash method?

[andrei-lazarov]

Some discussion here: #7

You can also manually trigger the update, if it doesn't come up.
Different project, but instructions are the same:
romasku/tuya-zigbee-switch#62

Lastly I think you need an OTA index file. It's like a dictionary: device -> firmware link

[pvvx]

https://github.com/pvvx/ZigbeeTLc/blob/master/bin/zg303z_sonoff2z.json

[malocycling]

Thanks for your answers. My configuration indeed was missing the z2m_*_index parameter. Just placing the firmware file was not enough.
Now when I trigger the firmware update via ZHA_toolkit I see a bunch of firmware files downloaded into the zigpy_ota folder.
This is the response I get after running the ota_notify command:

zha_toolkit_version: v1.1.29
zigpy_version: 0.83.0
zigpy_rf_version: 0.46.1
ieee_org: number.bodenfeuchte21_alarm_soil_moisture_min
ieee: a4:c1:38:d3:9b:97:23:84
command: ota_notify
command_data: null
start_time: "2025-10-24T12:15:35.928938+00:00"
errors: []
params:
  dir: 0
  tries: 1
  expect_reply: true
  args: []
  kwargs: {}
  read_before_write: true
  read_after_write: true
  download: true
PAR:
  cmd_id: null
  endpoint_id: null
  dst_endpoint_id: null
  cluster_id: null
  attr_id: null
  attr_type: null
  attr_val: null
  code: null
  min_interval: null
  max_interval: null
  reportable_change: null
  dir: 0
  manf: null
  tries: 1
  expect_reply: true
  args: []
  kwargs: {}
  state_id: null
  state_attr: null
  state_value_template: null
  force_update: false
  allow_create: false
  event_success: null
  event_fail: null
  event_done: null
  fail_exception: false
  read_before_write: true
  read_after_write: true
  write_if_equal: false
  csvfile: null
  csvlabel: null
  download: true
  path: null
  use_cache: false
  json_out: null
  json_timestamp: false
success: true

In the device itself I do not see any changes but I assume those would only take effect after the firmware had been updated, which might take some time. Unfortunately I do not see any progress or if it is updating at all.

Edit:
I don't see any OTA cluster for this device. Might this be causing the issues?

[pvvx]

I updated the original firmware with a programmer.
As a result, in ZIgbeeTLc, the following clusters exist:

And for ZHA I added the file lib64/python3.13/site-packages/zhaquirks/custom/telink2.py:

"""Telink TLSR825x based devices with custom firmware.

see https://github.com/pvvx/ZigbeeTLc
"""

from zigpy.quirks.v2 import QuirkBuilder
from zigpy.quirks.v2.homeassistant import PERCENTAGE, UnitOfTemperature, UnitOfTime
import zigpy.types as t
from zigpy.zcl import ClusterType
from zigpy.zcl.clusters.hvac import ScheduleProgrammingVisibility, UserInterface
from zigpy.zcl.foundation import ZCLAttributeDef

from zhaquirks import CustomCluster


class CustomUserInterfaceCluster(CustomCluster, UserInterface):
    """Custom User Interface Cluster with smiley control."""

    class AttributeDefs(UserInterface.AttributeDefs):
        """Attribute Definitions."""

        # A value in 0.01ºC offset to fix up incorrect values from sensor
        temperature_offset = ZCLAttributeDef(
            id=0x0100,
            type=t.int16s,
            access="rw",
            is_manufacturer_specific=True,
        )

        # A value in 0.01%RH offset to fix up incorrect values from sensor
        humidity_offset = ZCLAttributeDef(
            id=0x0101,
            type=t.int16s,
            access="rw",
            is_manufacturer_specific=True,
        )
        # Measurement interval, step 1 second, range: 3..255 seconds. Default 10 seconds.
        measurement_interval = ZCLAttributeDef(
            id=0x0107,
            type=t.uint8_t,
            access="rw",
            is_manufacturer_specific=True,
        )


(
    QuirkBuilder("Sonoff", "ZG-303Z-z")
    .removes(CustomUserInterfaceCluster.cluster_id, cluster_type=ClusterType.Client)
    .adds(CustomUserInterfaceCluster)
    .number(
        CustomUserInterfaceCluster.AttributeDefs.temperature_offset.name,
        CustomUserInterfaceCluster.cluster_id,
        min_value=-327.67,
        max_value=327.67,
        step=0.01,
        unit=UnitOfTemperature.CELSIUS,
        translation_key="temperature_offset",
        fallback_name="Temperature offset",
        multiplier=0.01,
        mode="box",
    )
    .number(
        CustomUserInterfaceCluster.AttributeDefs.humidity_offset.name,
        CustomUserInterfaceCluster.cluster_id,
        min_value=-327.67,
        max_value=327.67,
        step=0.01,
        unit=PERCENTAGE,
        translation_key="humidity_offset",
        fallback_name="Humidity offset",
        multiplier=0.01,
        mode="box",
    )
    .number(
        CustomUserInterfaceCluster.AttributeDefs.measurement_interval.name,
        CustomUserInterfaceCluster.cluster_id,
        min_value=3,
        max_value=255,
        unit=UnitOfTime.SECONDS,
        translation_key="measurement_interval",
        fallback_name="Measurement interval",
        mode="box",
    )
    .add_to_registry()
)

After linking, I renamed one of the "Humidity" to "Moisture."
Result:

[malocycling]

Thanks a lot! I was able to flash one sensor with a programmer and now am also seeing the OTA options like in your screenshot. I might try to find a solution to integrate the renaming of one humidity value directly into your quirk, because with a lot of those sensors I don't want to manually rename it for each one.
One remark on the firmware itself: I see a strange behavior of the LED as it no longer shines bright when the button is pressed but only very dim. Not sure whether this is the intended behavior?

[pvvx]

This chip cannot hold the GPIO output in sleep modes. The internal GPIO power is disabled during sleep, and the chip can only hold the internal resistance to GND or Vbat.
In the original firmware, when the LED is on, the CPU is also on, drawing significant power from the battery.
Tuya doesn't care how often you need to change the batteries.

---

Some circuits use an external transistor to drive the LED, which provides increased current to the LED during the chip's sleep modes.

---

The LED flashes when the “identification” function is operating and when the “binding” function is triggered.

[malocycling]

sorry for going OT on this but doesn't the CPU wake up once the button is pressed anyway? I mean the only reason the button is pressed is that the user is interacting with the sensor. And from a user perspective I think it makes sense that the sensor is 'confirming' this interaction by flashing the LED even though this is draining the batteries.

[juha63]

@malocycling
As far as I understand Igor, the led is lid only during processing the action (i.e. pressing the button). This is done in milliseconds, so you get the impression of a dimmed LED. In TUYA the CPU will stay waked up to let the LED shine bright.