Add Count-Up Timer Functionality #200
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
added 6 commits
February 13, 2025 20:41
…ed max_value
This commit introduces a major new feature: a count-up timer mode for the `timer-bar-card`. This allows you to display a progress bar that fills up over time, starting from a specified start time, either until a fixed maximum value is reached, or with a dynamically adjusting maximum.
**Key Features:**
* **Count-Up Mode:** The card now supports both countdown (existing functionality) and count-up modes. The mode is automatically selected based on the presence of `duration` (countdown) or `max_value` (count-up) in the configuration.
* **`max_value`:** Specifies the maximum value for the count-up timer. This can be a fixed duration string (e.g., "1y", "30m", "2h", "1d") or the special value `"auto"`.
* **`auto_increment`:** When `max_value` is set to `"auto"`, the `auto_increment` option (optional) controls how much the maximum value increases when the elapsed time gets close to the current maximum. Defaults to 1 hour. Uses the same duration string format as `max_value`.
* **`start_time`:** Allows you to specify a custom start time for the count-up timer. This can be:
* **`fixed`:** A fixed date/time string (e.g., "2023-10-26T12:00:00").
* **`entity`:** The state or attribute of another Home Assistant entity. This is particularly useful for using an `input_datetime` helper as the start time.
* `entity`: (Required) The entity ID.
* `attribute`: (Optional) The attribute of the entity to use (e.g., `timestamp` for `input_datetime`).
* `units`: (Required when using `attribute`) Specifies the units of the attribute value ("seconds", "minutes", "hours", "duration"). Use "seconds" when using the `timestamp` attribute.
* **`active_state`:** Consistent with the countdown timer, the count-up timer is only active when the main `entity` is in one of the specified `active_state` states.
* **Placeholder entity:** If you want use an static start time, but you don't have a sensor that always be "on", you need to add a placeholder `entity` (typically a `binary_sensor` or a template sensor) in the main `entity` field, and this must to be always `on`.
* **Dynamic Time Formatting:** The time display automatically switches between `MM:SS` and `HH:MM:SS` based on the elapsed time. A new `long` format option displays years, months, days, hours, minutes, and seconds. Custom format strings are also supported.
**Example Configuration (Count-up from input_datetime):**
```yaml
type: custom:timer-bar-card
name: Time Since Event
entity: binary_sensor.placeholder_always_on # Placeholder entity, always "on"
start_time:
entity: input_datetime.my_event_start_time
attribute: timestamp
units: seconds
max_value: auto
auto_increment: 1h
active_state: "on"
format: long
```
**Example Configuration (Count-up from sensor):**
```yaml
type: custom:timer-bar-card
name: Time Since Event
entity: binary_sensor.my_event_trigger
max_value: 2d
active_state: "on"
format: HH:MM:SS
```
**Bug Fixes:**
This commit includes several *critical* bug fixes related to the count-up timer:
* Fixed incorrect percentage calculation when using a fixed `max_value`. The progress bar now correctly reflects the elapsed time relative to the configured `max_value`.
* Fixed an issue where `timerTimePercent` wasn't correctly using the dynamic `_currentMaxValue` in "auto" mode.
* Fixed handling of `input_datetime` entities and their `timestamp` attribute for the `start_time`. The card now correctly interprets the timestamp value.
* Fixed an issue that could show `Invalid duration format` warning.
* Corrected the logic for time calculation
* Fixed issues related to types and arguments.
**Breaking Changes:**
* Although this release try to keep the compatibility, some configuration maybe need to be changed, mainly related to `duration` and `max_value` options.
**Notes:**
* The `entity` at the top level of the card configuration determines when the timer is active (based on `active_state`).
* The `start_time.entity` provides the *value* for the starting time.
* When using a `input_datetime`, is recommended to use `start_time` with `attribute: timestamp` and `units: seconds`.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This pull request introduces a significant new feature to the
timer-bar-card: count-up timer functionality. This allows the card to display the elapsed time since a specified event, in addition to the existing countdown timer capabilities.Key Features and Changes:
last_changedattribute (or a custom start time, if configured). This is activated by using themax_valueoption instead of thedurationoption.max_valueOption: This new option controls the count-up behavior:"1h","30m","90s"sets a fixed maximum value for the progress bar. The bar fills completely when the elapsed time reaches this value."auto": Enables automatic expansion of the maximum value. The bar's maximum value increases as the elapsed time approaches the current maximum, creating a continuously expanding time window.auto_incrementOption: Whenmax_valueis set to"auto", this option controls:"1h"if not specified. Accepts values like"15m","2h","30s".MM:SS(for times under 60 minutes) andHH:MM:SS(for times 60 minutes and over) whenresolution: automaticis set. This improves readability.durationandmax_value: The code now ensures that ifmax_valueis set,durationis effectively ignored (treated as null), and vice versa. This provides a clear and unambiguous way to switch between countdown and count-up modes.README.mdwith detailed explanations of the new features, configuration options, and examples. Added a new section highlighting the count-up functionality, similar to the existing Mushroom styling section.types.ts,timer-bar-card.ts,timer-bar-entity-row.ts,timer-bar-mushroom-row.ts,helpers.tsandformat-time.ts.Code Structure and Implementation Details:
helpers.ts(intimerTimeRemainingandtimerTimePercent) andtimer-bar-entity-row.ts(managing the_currentMaxValuestate for theautomode).durationis used.Testing:
max_value.max_value: auto.auto_incrementvalues.last_changed, etc.).Acknowledgments:
This feature was developed by Gustavo with significant assistance from Google's AI Studio. The collaborative process involved iterative refinement of the code, ensuring correct logic, type safety, and comprehensive documentation.
Example Configuration (Count-Up):