Add energy price calendar platform to Teslemetry

[Bre77]

Proposed change

Add calendar entities for energy site tariff schedules, providing:

• Buy tariff calendar showing energy purchase pricing periods
• Sell tariff calendar showing energy sell-back pricing periods

Features:

• Displays current active pricing period
• Shows seasonal pricing variations
• Handles time-of-use (TOU) periods
• Supports midnight crossing periods

This is a carve out from #142894

Type of change

• [ ] Dependency upgrade
• [ ] Bugfix (non-breaking change which fixes an issue)
• [ ] New integration (thank you!)
• [x] 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: https://github.com/home-assistant/home-assistant.io/pull/39306
• Link to developer documentation pull request:
• Link to frontend pull request:

Checklist

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

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

• [x] 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.

[joostlek]

I am wondering how well a calendar works for this. As in, people generally need this for raw data, while a calendar is used for things that happen during a day

[Bre77]

I am wondering how well a calendar works for this. As in, people generally need this for raw data, while a calendar is used for things that happen during a day

It works very well, it's time based and seasonal data. It lets users see the current value and future values.

[joostlek]

Right I agree that it shows, but I would argue that it's not a calendar thing. As in, if I would import this in my calendar app my app would be unusable.

[Bre77]

@joostlek are you saying this should just be a sensor entity with the current price?

[joostlek]

And maybe a service with json return for forecasting data. But I'm not sure if my opinion is shared by others so I'm open to other arguments

[dgomes]

I'm struggling with a similar use case (sensor vs calendar)

The calendar has the benefit of conveying future information as the sensor will only show current values.

If I want to do an automation that needs to know the future tariff start time and duration the sensor is not enough.

[Bre77]

@joostlek the best case I have, is that a sensor entity will only ever tell you whats happening now, but the calendar entity allows more flexible automations with offsets from the start and end of the segment. https://www.home-assistant.io/integrations/calendar/#automation

The primary usecase I can think of here is that Tesla Powerwalls take a few minutes for certain actions to take effect, so a user may wish to have automations run a few minutes before a certain tarrif period starts or ends.

I fully accept people may never want to see this on a calandar in the UI, but its calendar like data that the Home Assistant calendar platform serves well.

There is a future possibility that I will allow editing through the create and delete event actions.

[Bre77]

@joostlek can I please bump this review.

[joostlek]

I will throw this for in the architecture meeting on thursday

[Bre77]

@joostlek did you get an architecture answer on this?

[dgomes]

looking into this issue before submitting yet another integration tracking tariff using a calendar entity.

[emontnemery]

This was discussed in the architecture meeting, but it was forgotten to update here.

The conclusion was:

We should implement both action responses and a calendar entity, and explore to add it to the energy dashboard

I think it's fine to split that in two PRs: One which adds the calendar (this PR) and one which adds a service returning data.

[Bre77]

Thanks for letting me know @emontnemery, @joostlek does that mean we can push this one through?

[emontnemery]

@bre77 please address the review comments and mark the PR ready for review when done

[home-assistant[bot]]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks :+1:

Learn more about our pull request process.

[emontnemery]

I think more tests are needed as requested here: https://github.com/home-assistant/core/pull/145848#discussion_r2489603563

Please mark the PR "Ready for review" when tests have been added, or if you have some reason why it's not needed.

[silamon]

Came here from the documentation pull request. I see you've done changes but probably forgot to lift the draft status?

Kindly note that you're documentation branch needs a rebase onto next.

[Bre77]

Came here from the documentation pull request. I see you've done changes but probably forgot to lift the draft status?

Kindly note that you're documentation branch needs a rebase onto next.

I was requested to add more tests, which I have not had time to do yet. I'll hopefully get this over the line soon.