Matter OperationalState CountdownTime #147705

lboue · 2025-06-28T06:31:44Z

Proposed change

Matter OperationalState CountdownTime. This attribute SHALL represent the estimated time left before the operation is completed, in seconds.
Used for appliances like MWO or Dishwasher.

It can be tested with this example:
https://github.com/tomasmcguinness/matter-esp32-acme-dishwasher

Specs

This attribute SHALL represent the estimated time left before the operation is completed, in seconds.
A value of 0 (zero) means that the operation has completed.
A value of null represents that there is no time currently defined until operation completion. This MAY happen, for example, because no operation is in progress or because the completion time is unknown.
Changes to this attribute SHALL only be marked as reportable in the following cases:
• If it has changed due to a change in the CurrentPhase or OperationalState attributes, or
• When it changes from 0 to any other value and vice versa, or
• When it changes from null to any other value and vice versa, or
• When it increases, or
• When there is any increase or decrease in the estimated time remaining that was due to progressing insight of the server’s control logic, or
• When it changes at a rate significantly different from one unit per second.
Changes to this attribute merely due to the normal passage of time with no other dynamic change of device state SHALL NOT be reported.
As this attribute is not being reported during a regular countdown, clients SHOULD NOT rely on the reporting of this attribute in order to keep track of the remaining duration.

Type of change

Dependency upgrade
Bugfix (non-breaking change which fixes an issue)
New integration (thank you!)
New feature (which adds functionality to an existing integration)
Deprecation (breaking change to happen in the future)
Breaking change (fix/feature causing existing functionality to break)
Code quality improvements to existing code or addition of tests

Additional information

This PR fixes or closes issue: fixes #
This PR is related to issue:
Link to documentation pull request:
Link to developer documentation pull request:
Link to frontend pull request:

Checklist

The code change is tested and works locally.
Local tests pass. Your PR cannot be merged unless tests pass
There is no commented out code in this PR.
I have followed the development checklist
I have followed the perfect PR recommendations
The code has been formatted using Ruff (ruff format homeassistant tests)
Tests have been added to verify that the new code works.

If user exposed functionality or configuration variables are added/changed:

Documentation added/updated for www.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

The manifest file has all fields filled out correctly.
Updated and included derived files by running: python3 -m script.hassfest.
New or updated dependencies have been added to requirements_all.txt.
Updated by running python3 -m script.gen_requirements_all.
For the updated dependencies - a link to the changelog, or at minimum a diff between library versions is added to the PR description.

To help with the load of incoming pull requests:

I have reviewed two other open pull requests in this repository.

home-assistant · 2025-06-28T06:31:49Z

Hey there @home-assistant/matter, mind taking a look at this pull request as it has been labeled with an integration (matter) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of matter can trigger bot actions by commenting:

@home-assistant close Closes the pull request.
@home-assistant rename Awesome new title Renames the pull request.
@home-assistant reopen Reopen the pull request.
@home-assistant unassign matter Removes the current integration label and assignees on the pull request, add the integration domain after the command.
@home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component) to the pull request.
@home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component) on the pull request.

MartinHjelmare · 2025-06-28T08:09:52Z

homeassistant/components/matter/sensor.py

+            translation_key="countdown_time",
+            native_unit_of_measurement=UnitOfTime.SECONDS,
+            suggested_unit_of_measurement=UnitOfTime.MINUTES,
+            device_class=SensorDeviceClass.DURATION,


Shouldn't this be a timestamp sensor instead? According to the specs it is not reported changed due to normal passage of time (ie a decrease of 1 / s) but only for significant changes, like recalculation in server, increase of time, going from or to 0 etc.

If we use a duration sensor instead of a timestamp sensor this sensor will have the wrong state for the whole duration after the first report until it reaches 0.

Yes, the way it works is quite special.
You mean do a calculation to determine the timestamp of the end time?

Timestamp requires native_value to return a Python datetime.datetime object, with time zone information.
So we should use SensorDeviceClass.DATE instead?

The snapshot test does not work because the current date changes with each run. Is there a way around this?

Use the freezer fixture and set a datetime.

Example:

core/tests/components/tod/test_binary_sensor.py

Lines 107 to 131 in 60e3b38

async def test_midnight_turnover_after_midnight_inside_period(

hass: HomeAssistant, freezer: FrozenDateTimeFactory, hass_tz_info

) -> None:

"""Test midnight turnover setting before midnight inside period ."""

test_time = datetime(2019, 1, 10, 21, 0, 0, tzinfo=hass_tz_info)

config = {

"binary_sensor": [

{"platform": "tod", "name": "Night", "after": "22:00", "before": "5:00"}

]

}

freezer.move_to(test_time)

await async_setup_component(hass, "binary_sensor", config)

await hass.async_block_till_done()

state = hass.states.get("binary_sensor.night")

assert state.state == STATE_OFF

await hass.async_block_till_done()

freezer.move_to(test_time + timedelta(hours=1))

async_fire_time_changed(hass, dt_util.utcnow())

await hass.async_block_till_done()

state = hass.states.get("binary_sensor.night")

assert state.state == STATE_ON

Use UTC time. The sensor base class will convert to UTC if it's not already UTC time.

…urement logic

OperationalState CountdownTime

6699e28

home-assistant bot added cla-signed has-tests integration: matter new-feature small-pr PRs with less than 30 lines. labels Jun 28, 2025

home-assistant bot added the Quality Scale: No score label Jun 28, 2025

lboue marked this pull request as ready for review June 28, 2025 07:32

lboue requested a review from a team as a code owner June 28, 2025 07:32

MartinHjelmare reviewed Jun 28, 2025

View reviewed changes

MartinHjelmare marked this pull request as draft June 28, 2025 08:12

lboue added 3 commits July 1, 2025 15:55

Update countdown time sensor to use date device class and adjust meas…

003e9ed

…urement logic

Update snapshots

4332b2d

Refactor OperationalStateCountdownTime to remove state_class

5ac0ea9

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Matter OperationalState CountdownTime #147705

Matter OperationalState CountdownTime #147705

lboue commented Jun 28, 2025 •

edited

Loading

Uh oh!

home-assistant bot commented Jun 28, 2025

Uh oh!

MartinHjelmare Jun 28, 2025

Uh oh!

lboue Jun 28, 2025

Uh oh!

MartinHjelmare Jun 28, 2025

Uh oh!

lboue Jul 1, 2025

Uh oh!

lboue Jul 1, 2025

Uh oh!

MartinHjelmare Jul 1, 2025

Uh oh!

MartinHjelmare Jul 1, 2025

Uh oh!

Uh oh!

	async def test_midnight_turnover_after_midnight_inside_period(
	hass: HomeAssistant, freezer: FrozenDateTimeFactory, hass_tz_info
	) -> None:
	"""Test midnight turnover setting before midnight inside period ."""
	test_time = datetime(2019, 1, 10, 21, 0, 0, tzinfo=hass_tz_info)
	config = {
	"binary_sensor": [
	{"platform": "tod", "name": "Night", "after": "22:00", "before": "5:00"}
	]
	}
	freezer.move_to(test_time)
	await async_setup_component(hass, "binary_sensor", config)
	await hass.async_block_till_done()

	state = hass.states.get("binary_sensor.night")
	assert state.state == STATE_OFF

	await hass.async_block_till_done()

	freezer.move_to(test_time + timedelta(hours=1))
	async_fire_time_changed(hass, dt_util.utcnow())

	await hass.async_block_till_done()
	state = hass.states.get("binary_sensor.night")
	assert state.state == STATE_ON

Uh oh!

Matter OperationalState CountdownTime #147705

Are you sure you want to change the base?

Matter OperationalState CountdownTime #147705

Conversation

lboue commented Jun 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed change

Specs

Type of change

Additional information

Checklist

Uh oh!

home-assistant bot commented Jun 28, 2025

Uh oh!

MartinHjelmare Jun 28, 2025

Choose a reason for hiding this comment

Uh oh!

lboue Jun 28, 2025

Choose a reason for hiding this comment

Uh oh!

MartinHjelmare Jun 28, 2025

Choose a reason for hiding this comment

Uh oh!

lboue Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

lboue Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

MartinHjelmare Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

MartinHjelmare Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lboue commented Jun 28, 2025 •

edited

Loading