Compare commits

..

No commits in common. "main" and "v0.10.1" have entirely different histories.

520 changed files with 8481 additions and 144696 deletions

View file

@ -1,29 +1,18 @@
{
"name": "jpawlowski/hass.tibber_prices",
"image": "mcr.microsoft.com/devcontainers/python:3.14",
"postCreateCommand": "bash .devcontainer/setup-git.sh && scripts/setup/setup",
"image": "mcr.microsoft.com/devcontainers/python:3.13",
"postCreateCommand": "scripts/setup",
"postStartCommand": "scripts/motd",
"containerEnv": {
"PYTHONASYNCIODEBUG": "1",
"TIBBER_PRICES_DEV": "1"
"PYTHONASYNCIODEBUG": "1"
},
"forwardPorts": [
8123,
3000,
3001
8123
],
"portsAttributes": {
"8123": {
"label": "Home Assistant",
"onAutoForward": "notify"
},
"3000": {
"label": "Docusaurus User Docs",
"onAutoForward": "notify"
},
"3001": {
"label": "Docusaurus Developer Docs",
"onAutoForward": "notify"
}
},
"customizations": {
@ -38,7 +27,7 @@
"ms-python.vscode-pylance",
"ms-vscode-remote.remote-containers",
"redhat.vscode-yaml",
"ryanluker.vscode-coverage-gutters"
"ryanluker.vscode-coverage-gutters",
],
"settings": {
"editor.tabSize": 4,
@ -50,15 +39,6 @@
"python.analysis.typeCheckingMode": "basic",
"python.analysis.autoImportCompletions": true,
"python.analysis.diagnosticMode": "workspace",
"python.analysis.diagnosticSeverityOverrides": {
"reportUnusedImport": "none",
"reportUnusedVariable": "none",
"reportUnusedCoroutine": "none",
"reportMissingTypeStubs": "none"
},
"python.analysis.include": [
"custom_components/tibber_prices"
],
"python.analysis.exclude": [
"**/.venv/**",
"**/venv/**",
@ -70,7 +50,7 @@
],
"python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
"python.analysis.extraPaths": [
"${workspaceFolder}/.venv/lib/python3.14/site-packages"
"${workspaceFolder}/.venv/lib/python3.13/site-packages"
],
"python.terminal.activateEnvironment": true,
"python.terminal.activateEnvInCurrentTerminal": true,
@ -105,30 +85,23 @@
"fileMatch": [
"homeassistant/components/*/manifest.json"
],
"url": "${containerWorkspaceFolder}/schemas/json/manifest_schema.json"
"url": "${containerWorkspaceFolder}/scripts/json_schemas/manifest_schema.json"
},
{
"fileMatch": [
"homeassistant/components/*/translations/*.json"
],
"url": "${containerWorkspaceFolder}/schemas/json/translation_schema.json"
"url": "${containerWorkspaceFolder}/scripts/json_schemas/translation_schema.json"
}
],
"git.useConfigOnly": false
]
}
}
},
"mounts": [
"source=${localEnv:HOME}${localEnv:USERPROFILE}/.gitconfig,target=/home/vscode/.gitconfig.host,type=bind,consistency=cached"
],
"remoteUser": "vscode",
"features": {
"ghcr.io/devcontainers/features/github-cli:1": {},
"ghcr.io/flexwie/devcontainer-features/op:1": {
"version": "latest"
},
"ghcr.io/devcontainers/features/node:1": {
"version": "24"
"version": "22"
},
"ghcr.io/devcontainers/features/rust:1": {
"version": "latest",

View file

@ -1,99 +0,0 @@
#!/bin/bash
# Setup Git configuration from host
# This script is idempotent and can be run multiple times safely.
# Exit on error
set -e
# Check if host gitconfig exists
if [ ! -f ~/.gitconfig.host ]; then
echo "No host .gitconfig found, skipping Git setup"
exit 0
fi
echo "Setting up Git configuration from host..."
# Extract and set user info
USER_NAME=$(grep -A 2 '^\[user\]' ~/.gitconfig.host | grep 'name' | sed 's/.*= //' | xargs)
USER_EMAIL=$(grep -A 2 '^\[user\]' ~/.gitconfig.host | grep 'email' | sed 's/.*= //' | xargs)
if [ -n "$USER_NAME" ]; then
CURRENT_NAME=$(git config --global user.name 2>/dev/null || echo "")
if [ "$CURRENT_NAME" != "$USER_NAME" ]; then
git config --global user.name "$USER_NAME"
echo "✓ Set user.name: $USER_NAME"
else
echo " user.name already set: $USER_NAME"
fi
fi
if [ -n "$USER_EMAIL" ]; then
CURRENT_EMAIL=$(git config --global user.email 2>/dev/null || echo "")
if [ "$CURRENT_EMAIL" != "$USER_EMAIL" ]; then
git config --global user.email "$USER_EMAIL"
echo "✓ Set user.email: $USER_EMAIL"
else
echo " user.email already set: $USER_EMAIL"
fi
fi
# Set safe defaults for container
git config --global init.defaultBranch main
git config --global pull.rebase false
git config --global merge.conflictStyle diff3
git config --global submodule.recurse true
git config --global color.ui true
echo "✓ Set Git defaults"
# Copy useful aliases (skip if they have macOS-specific paths)
if grep -q '^\[alias\]' ~/.gitconfig.host; then
echo "✓ Syncing Git aliases..."
# First, collect all aliases from host config
TEMP_ALIASES=$(mktemp)
sed -n '/^\[alias\]/,/^\[/p' ~/.gitconfig.host | \
grep -v '^\[' | \
grep -v '^$' | \
while IFS= read -r line; do
# Skip aliases with macOS-specific paths
if echo "$line" | grep -q -E '/(Applications|usr/local)'; then
continue
fi
echo "$line" >> "$TEMP_ALIASES"
done
# Apply each alias (git config --global overwrites existing values = idempotent)
if [ -s "$TEMP_ALIASES" ]; then
while IFS= read -r line; do
ALIAS_NAME=$(echo "$line" | awk '{print $1}')
ALIAS_VALUE=$(echo "$line" | sed "s/^$ALIAS_NAME = //")
git config --global "alias.$ALIAS_NAME" "$ALIAS_VALUE" 2>/dev/null || true
done < "$TEMP_ALIASES"
echo " Synced $(wc -l < "$TEMP_ALIASES") aliases"
fi
rm -f "$TEMP_ALIASES"
fi
# Disable GPG signing in container (1Password SSH signing doesn't work in DevContainers)
# SSH agent forwarding works for git push/pull, but SSH signing requires direct
# access to 1Password app which isn't available in the container.
#
# For signed commits: Make final commits on host macOS where 1Password is available.
# The container is for development/testing - pre-commit hooks will still run.
CURRENT_SIGNING=$(git config --global commit.gpgsign 2>/dev/null || echo "false")
if [ "$CURRENT_SIGNING" != "false" ]; then
echo " Disabling commit signing in container (1Password not accessible)"
echo " → For signed commits, commit from macOS terminal outside container"
git config --global commit.gpgsign false
else
echo " Commit signing already disabled"
fi
# Keep the signing key info for reference, but don't use it
SIGNING_KEY=$(grep 'signingkey' ~/.gitconfig.host 2>/dev/null | sed 's/.*= //' | xargs || echo "")
if [ -n "$SIGNING_KEY" ]; then
echo " → Your signing key: ${SIGNING_KEY:0:20}... (available on host)"
fi
echo "✓ Git configuration complete"

4
.github/FUNDING.yml vendored
View file

@ -1,4 +0,0 @@
# These are supported funding model platforms
github: [ jpawlowski ]
buy_me_a_coffee: jpawlowski

View file

@ -20,7 +20,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v6
uses: actions/checkout@v5.0.1
with:
fetch-depth: 0 # Need full history for git describe
@ -43,13 +43,13 @@ jobs:
echo "✗ Tag v${{ steps.manifest.outputs.version }} does not exist yet"
fi
- name: Validate version format (stable or beta)
- name: Validate version format
if: steps.tag_check.outputs.exists == 'false'
run: |
VERSION="${{ steps.manifest.outputs.version }}"
if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+(b[0-9]+)?$'; then
if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
echo "❌ Invalid version format: $VERSION"
echo "Expected format: X.Y.Z or X.Y.ZbN (e.g., 1.0.0, 0.25.0b0)"
echo "Expected format: X.Y.Z (e.g., 1.0.0)"
exit 1
fi
echo "✓ Version format valid: $VERSION"

View file

@ -1,163 +0,0 @@
name: Deploy Docusaurus Documentation (Dual Sites)
on:
push:
branches: [main]
paths:
- 'docs/**'
- '.github/workflows/docusaurus.yml'
tags:
- 'v*.*.*'
workflow_dispatch:
# Concurrency control: cancel in-progress deployments
# Pattern from GitHub Actions best practices for deployment workflows
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
permissions:
contents: write
pages: write
id-token: write
jobs:
deploy:
name: Build and Deploy Documentation Sites
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0 # Needed for version timestamps
- name: Detect prerelease tag (beta/rc)
id: taginfo
run: |
if [[ "${GITHUB_REF}" =~ ^refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(b[0-9]+|rc[0-9]+)$ ]]; then
echo "is_prerelease=true" >> "$GITHUB_OUTPUT"
echo "Detected prerelease tag: ${GITHUB_REF}"
else
echo "is_prerelease=false" >> "$GITHUB_OUTPUT"
echo "Stable tag or branch: ${GITHUB_REF}"
fi
- uses: actions/setup-node@v6
with:
node-version: 24
cache: 'npm'
cache-dependency-path: |
docs/user/package-lock.json
docs/developer/package-lock.json
# USER DOCS BUILD
- name: Install user docs dependencies
working-directory: docs/user
run: npm ci
- name: Create user docs version snapshot on tag
if: startsWith(github.ref, 'refs/tags/v') && steps.taginfo.outputs.is_prerelease != 'true'
working-directory: docs/user
run: |
TAG_VERSION=${GITHUB_REF#refs/tags/}
echo "Creating user documentation version: $TAG_VERSION"
npm run docusaurus docs:version $TAG_VERSION || echo "Version already exists"
# Update GitHub links in versioned docs
if [ -d "versioned_docs/version-$TAG_VERSION" ]; then
find versioned_docs/version-$TAG_VERSION -name "*.md" -type f -exec sed -i "s|github.com/jpawlowski/hass.tibber_prices/blob/main/|github.com/jpawlowski/hass.tibber_prices/blob/$TAG_VERSION/|g" {} \; || true
fi
- name: Cleanup old user docs versions
if: startsWith(github.ref, 'refs/tags/v') && steps.taginfo.outputs.is_prerelease != 'true'
working-directory: docs/user
run: |
chmod +x ../cleanup-old-versions.sh
# Adapt script for single-instance mode (versioned_docs/ instead of user_versioned_docs/)
sed 's/user_versioned_docs/versioned_docs/g; s/user_versions.json/versions.json/g; s/developer_versioned_docs/versioned_docs/g; s/developer_versions.json/versions.json/g' ../cleanup-old-versions.sh > cleanup-single.sh
chmod +x cleanup-single.sh
./cleanup-single.sh
- name: Build user docs website
working-directory: docs/user
run: npm run build
# DEVELOPER DOCS BUILD
- name: Install developer docs dependencies
working-directory: docs/developer
run: npm ci
- name: Create developer docs version snapshot on tag
if: startsWith(github.ref, 'refs/tags/v') && steps.taginfo.outputs.is_prerelease != 'true'
working-directory: docs/developer
run: |
TAG_VERSION=${GITHUB_REF#refs/tags/}
echo "Creating developer documentation version: $TAG_VERSION"
npm run docusaurus docs:version $TAG_VERSION || echo "Version already exists"
# Update GitHub links in versioned docs
if [ -d "versioned_docs/version-$TAG_VERSION" ]; then
find versioned_docs/version-$TAG_VERSION -name "*.md" -type f -exec sed -i "s|github.com/jpawlowski/hass.tibber_prices/blob/main/|github.com/jpawlowski/hass.tibber_prices/blob/$TAG_VERSION/|g" {} \; || true
fi
- name: Cleanup old developer docs versions
if: startsWith(github.ref, 'refs/tags/v') && steps.taginfo.outputs.is_prerelease != 'true'
working-directory: docs/developer
run: |
chmod +x ../cleanup-old-versions.sh
# Adapt script for single-instance mode
sed 's/user_versioned_docs/versioned_docs/g; s/user_versions.json/versions.json/g; s/developer_versioned_docs/versioned_docs/g; s/developer_versions.json/versions.json/g' ../cleanup-old-versions.sh > cleanup-single.sh
chmod +x cleanup-single.sh
./cleanup-single.sh
- name: Build developer docs website
working-directory: docs/developer
run: npm run build
# MERGE BUILDS
- name: Merge both documentation sites
run: |
mkdir -p deploy-root/user
mkdir -p deploy-root/developer
cp docs/index.html deploy-root/
cp -r docs/user/build/* deploy-root/user/
cp -r docs/developer/build/* deploy-root/developer/
# COMMIT VERSION SNAPSHOTS
- name: Commit version snapshots back to repository
if: startsWith(github.ref, 'refs/tags/v') && steps.taginfo.outputs.is_prerelease != 'true'
run: |
TAG_VERSION=${GITHUB_REF#refs/tags/}
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
# Add version files from both docs
git add docs/user/versioned_docs/ docs/user/versions.json 2>/dev/null || true
git add docs/developer/versioned_docs/ docs/developer/versions.json 2>/dev/null || true
# Commit if there are changes
if git diff --staged --quiet; then
echo "No version snapshot changes to commit"
else
git commit -m "docs: add version snapshot $TAG_VERSION and cleanup old versions [skip ci]"
git push origin HEAD:main
echo "Version snapshots committed and pushed to main"
fi
# DEPLOY TO GITHUB PAGES
- name: Setup Pages
uses: actions/configure-pages@v6
- name: Upload artifact
uses: actions/upload-pages-artifact@v4
with:
path: ./deploy-root
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v5

View file

@ -4,15 +4,9 @@ on:
push:
branches:
- "main"
paths-ignore:
- 'docs/**'
- '.github/workflows/docusaurus.yml'
pull_request:
branches:
- "main"
paths-ignore:
- 'docs/**'
- '.github/workflows/docusaurus.yml'
permissions: {}
@ -26,20 +20,20 @@ jobs:
runs-on: "ubuntu-latest"
steps:
- name: Checkout the repository
uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
- name: Set up Python
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
with:
python-version: "3.14"
python-version: "3.13"
- name: Install uv
uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7.1.3
with:
version: "0.9.3"
- name: Install requirements
run: scripts/setup/bootstrap
run: scripts/bootstrap
- name: Lint check
run: scripts/lint-check

View file

@ -27,7 +27,7 @@ jobs:
version: ${{ steps.tag.outputs.version }}
steps:
- name: Checkout repository
uses: actions/checkout@v6
uses: actions/checkout@v5.0.1
with:
fetch-depth: 0
token: ${{ secrets.GITHUB_TOKEN }}
@ -77,36 +77,22 @@ jobs:
- name: Commit and push manifest.json update
if: steps.update.outputs.updated == 'true'
run: |
TAG_VERSION="v${{ steps.tag.outputs.version }}"
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add custom_components/tibber_prices/manifest.json
git commit -m "chore(release): sync manifest.json with tag ${TAG_VERSION}"
git commit -m "chore(release): sync manifest.json with tag v${{ steps.tag.outputs.version }}"
# Push to main branch
git push origin HEAD:main
# Delete and recreate tag on new commit
echo "::notice::Recreating tag ${TAG_VERSION} on updated commit"
git tag -d "${TAG_VERSION}"
git push origin :refs/tags/"${TAG_VERSION}"
git tag -a "${TAG_VERSION}" -m "Release ${TAG_VERSION}"
git push origin "${TAG_VERSION}"
# Delete existing release if present (will be recreated by release-notes job)
gh release delete "${TAG_VERSION}" --yes --cleanup-tag=false || echo "No existing release to delete"
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
release-notes:
name: Generate and publish release notes
runs-on: ubuntu-latest
needs: sync-manifest # Wait for manifest sync to complete
steps:
- name: Checkout repository
uses: actions/checkout@v6
uses: actions/checkout@v5.0.1
with:
fetch-depth: 0 # Fetch all history for git-cliff
ref: main # Use updated main branch if manifest was synced
@ -135,20 +121,10 @@ jobs:
FEAT=$(echo "$COMMITS" | grep -cE "^feat(\(.+\))?:" || true)
FIX=$(echo "$COMMITS" | grep -cE "^fix(\(.+\))?:" || true)
parse_version() {
local version="$1"
if [[ $version =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)(b[0-9]+)?$ ]]; then
echo "${BASH_REMATCH[1]} ${BASH_REMATCH[2]} ${BASH_REMATCH[3]} ${BASH_REMATCH[4]}"
else
echo "Invalid version format: $version" >&2
exit 1
fi
}
# Parse versions (support beta/prerelease suffix like 0.25.0b0)
# Parse versions
PREV_VERSION="${PREV_TAG#v}"
read -r PREV_MAJOR PREV_MINOR PREV_PATCH PREV_PRERELEASE <<< "$(parse_version "$PREV_VERSION")"
read -r MAJOR MINOR PATCH PRERELEASE <<< "$(parse_version "$TAG_VERSION")"
IFS='.' read -r PREV_MAJOR PREV_MINOR PREV_PATCH <<< "$PREV_VERSION"
IFS='.' read -r MAJOR MINOR PATCH <<< "$TAG_VERSION"
WARNING=""
SUGGESTION=""
@ -190,11 +166,9 @@ jobs:
echo "**Commits analyzed:** Breaking=$BREAKING, Features=$FEAT, Fixes=$FIX"
echo ""
echo "**To fix:**"
echo "1. Run locally: \`./scripts/release/suggest-version\`"
echo "2. Create correct tag: \`./scripts/release/prepare <suggested-version>\`"
echo "3. Push the corrected tag: \`git push origin v<suggested-version>\`"
echo ""
echo "**This tag will be automatically deleted in the next step.**"
echo "1. Delete the tag: \`git tag -d v$TAG_VERSION && git push origin :refs/tags/v$TAG_VERSION\`"
echo "2. Run locally: \`./scripts/suggest-version\`"
echo "3. Create correct tag: \`./scripts/prepare-release X.Y.Z\`"
echo "EOF"
} >> $GITHUB_OUTPUT
else
@ -202,19 +176,7 @@ jobs:
echo "warning=" >> $GITHUB_OUTPUT
fi
- name: Delete inappropriate version tag
if: steps.version_check.outputs.warning != ''
run: |
TAG_NAME="${GITHUB_REF#refs/tags/}"
echo "❌ Deleting tag $TAG_NAME (version not appropriate for changes)"
echo ""
echo "${{ steps.version_check.outputs.warning }}"
echo ""
git push origin --delete "$TAG_NAME"
exit 1
- name: Install git-cliff
if: steps.version_check.outputs.warning == ''
run: |
wget https://github.com/orhun/git-cliff/releases/download/v2.4.0/git-cliff-2.4.0-x86_64-unknown-linux-gnu.tar.gz
tar -xzf git-cliff-2.4.0-x86_64-unknown-linux-gnu.tar.gz
@ -222,7 +184,6 @@ jobs:
git-cliff --version
- name: Generate release notes
if: steps.version_check.outputs.warning == ''
id: release_notes
run: |
FROM_TAG="${{ steps.previoustag.outputs.previous_tag }}"
@ -232,7 +193,7 @@ jobs:
# Use our script with git-cliff backend (AI disabled in CI)
# git-cliff will handle filtering via cliff.toml
USE_AI=false ./scripts/release/generate-notes "${FROM_TAG}" "${TO_TAG}" > release-notes.md
USE_AI=false ./scripts/generate-release-notes "${FROM_TAG}" "${TO_TAG}" > release-notes.md
# Extract title from release notes (first line starting with "# ")
TITLE=$(head -n 1 release-notes.md | sed 's/^# //')
@ -241,6 +202,15 @@ jobs:
fi
echo "title=$TITLE" >> $GITHUB_OUTPUT
# Append version warning if present
WARNING="${{ steps.version_check.outputs.warning }}"
if [ -n "$WARNING" ]; then
echo "" >> release-notes.md
echo "---" >> release-notes.md
echo "" >> release-notes.md
echo "$WARNING" >> release-notes.md
fi
# Output for GitHub Actions
{
echo 'notes<<EOF'
@ -248,20 +218,25 @@ jobs:
echo EOF
} >> $GITHUB_OUTPUT
- name: Version Check Summary
if: steps.version_check.outputs.warning != ''
run: |
echo "### ⚠️ Version Mismatch Detected" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "${{ steps.version_check.outputs.warning }}" >> $GITHUB_STEP_SUMMARY
- name: Create GitHub Release
if: steps.version_check.outputs.warning == ''
uses: softprops/action-gh-release@v2
with:
name: ${{ steps.release_notes.outputs.title }}
body: ${{ steps.release_notes.outputs.notes }}
draft: false
prerelease: ${{ contains(github.ref, 'b') }}
prerelease: false
generate_release_notes: false # We provide our own
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Summary
if: steps.version_check.outputs.warning == ''
run: |
echo "✅ Release notes generated and published!" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY

View file

@ -7,15 +7,9 @@ on:
push:
branches:
- main
paths-ignore:
- 'docs/**'
- '.github/workflows/docusaurus.yml'
pull_request:
branches:
- main
paths-ignore:
- 'docs/**'
- '.github/workflows/docusaurus.yml'
permissions: {}
@ -29,10 +23,10 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout the repository
uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
- name: Run hassfest validation
uses: home-assistant/actions/hassfest@d56d093b9ab8d2105bc0cb6ee9bcc0ef4ec8b96d # master
uses: home-assistant/actions/hassfest@8ca6e134c077479b26138bd33520707e8d94ef59 # master
hacs: # https://github.com/hacs/action
name: HACS validation
@ -42,3 +36,5 @@ jobs:
uses: hacs/action@d556e736723344f83838d08488c983a15381059a # 22.5.0
with:
category: integration
# Remove this 'ignore' key when you have added brand images for your custom integration to https://github.com/home-assistant/brands
ignore: brands

802
AGENTS.md

File diff suppressed because it is too large Load diff

View file

@ -122,23 +122,13 @@ Always run before committing:
- Enrich price data before exposing to entities
- Follow Home Assistant entity naming conventions
See [Coding Guidelines](docs/developer/docs/coding-guidelines.md) for complete details.
See [Coding Guidelines](docs/development/coding-guidelines.md) for complete details.
## Documentation
Documentation is organized in two Docusaurus sites:
- **User docs** (`docs/user/`): Installation, configuration, usage guides
- Markdown files in `docs/user/docs/*.md`
- Navigation via `docs/user/sidebars.ts`
- **Developer docs** (`docs/developer/`): Architecture, patterns, contribution guides
- Markdown files in `docs/developer/docs/*.md`
- Navigation via `docs/developer/sidebars.ts`
**When adding new documentation:**
1. Place file in appropriate `docs/*/docs/` directory
2. Add to corresponding `sidebars.ts` for navigation
3. Update translations when changing `translations/en.json` (update ALL language files)
- **User guides**: Place in `docs/user/` (installation, configuration, usage)
- **Developer guides**: Place in `docs/development/` (architecture, patterns)
- **Update translations**: When changing `translations/en.json`, update ALL language files
## Reporting Bugs

103
README.md
View file

@ -1,8 +1,4 @@
# Tibber Prices - Custom Home Assistant Integration
<p align="center">
<img src="images/header.svg" alt="Tibber Prices Custom Integration for Tibber" width="600">
</p>
# Tibber Price Information & Ratings
[![GitHub Release][releases-shield]][releases]
[![GitHub Activity][commits-shield]][commits]
@ -10,41 +6,30 @@
[![hacs][hacsbadge]][hacs]
[![Project Maintenance][maintenance-shield]][user_profile]
[![BuyMeCoffee][buymecoffeebadge]][buymecoffee]
<a href="https://www.buymeacoffee.com/jpawlowski" target="_blank"><img src="images/bmc-button.svg" alt="Buy Me A Coffee" height="41" width="174"></a>
A Home Assistant integration that provides advanced price information and ratings from Tibber. This integration fetches **quarter-hourly** electricity prices, enriches them with statistical analysis, and provides smart indicators to help you optimize your energy consumption and save money.
> **⚠️ Not affiliated with Tibber**
> This is an independent, community-maintained custom integration for Home Assistant. It is **not** an official Tibber product and is **not** affiliated with or endorsed by Tibber AS.
A custom Home Assistant integration that provides advanced electricity price information and ratings from Tibber. This integration fetches **quarter-hourly** electricity prices, enriches them with statistical analysis, and provides smart indicators to help you optimize your energy consumption and save money.
![Tibber Price Information & Ratings](images/logo.png)
## 📖 Documentation
**[📚 Complete Documentation](https://jpawlowski.github.io/hass.tibber_prices/)** - Two comprehensive documentation sites:
- **[👤 User Documentation](https://jpawlowski.github.io/hass.tibber_prices/user/)** - Installation, configuration, usage guides, and examples
- **[🔧 Developer Documentation](https://jpawlowski.github.io/hass.tibber_prices/developer/)** - Architecture, contributing guidelines, and development setup
**Quick Links:**
- [Installation Guide](https://jpawlowski.github.io/hass.tibber_prices/user/installation) - Step-by-step setup instructions
- [Sensor Reference](https://jpawlowski.github.io/hass.tibber_prices/user/sensors) - Complete list of all sensors and attributes
- [Chart Examples](https://jpawlowski.github.io/hass.tibber_prices/user/chart-examples) - ApexCharts visualizations
- [Automation Examples](https://jpawlowski.github.io/hass.tibber_prices/user/automation-examples) - Real-world automation scenarios
- [Changelog](https://github.com/jpawlowski/hass.tibber_prices/releases) - Release history and notes
- **[User Guide](docs/user/)** - Installation, configuration, and usage guides
- **[Period Calculation](docs/user/period-calculation.md)** - How Best/Peak Price periods are calculated
- **[Developer Guide](docs/development/)** - Contributing, architecture, and release process
- **[Changelog](https://github.com/jpawlowski/hass.tibber_prices/releases)** - Release history and notes
## ✨ Features
- **Quarter-Hourly Price Data**: Access detailed 15-minute interval pricing (384 data points across 4 days: day before yesterday/yesterday/today/tomorrow)
- **Flexible Currency Display**: Choose between base currency (€, kr) or subunit (ct, øre) display - configurable per your preference with smart defaults
- **Quarter-Hourly Price Data**: Access detailed 15-minute interval pricing (192 data points across yesterday/today/tomorrow)
- **Current and Next Interval Prices**: Get real-time price data in both major currency (€, kr) and minor units (ct, øre)
- **Multi-Currency Support**: Automatic detection and formatting for EUR, NOK, SEK, DKK, USD, and GBP
- **Price Level Indicators**: Know when you're in a VERY_CHEAP, CHEAP, NORMAL, EXPENSIVE, or VERY_EXPENSIVE period
- **Statistical Sensors**: Track lowest, highest, and average prices for the day
- **Price Ratings**: Quarter-hourly ratings comparing current prices to 24-hour trailing averages
- **Smart Indicators**: Binary sensors to detect peak hours and best price hours for automations
- **Beautiful ApexCharts**: Auto-generated chart configurations with dynamic Y-axis scaling ([see examples](https://jpawlowski.github.io/hass.tibber_prices/user/chart-examples))
- **Chart Metadata Sensor**: Dynamic chart configuration for optimal visualization
- **Intelligent Caching**: Minimizes API calls while ensuring data freshness across Home Assistant restarts
- **Custom Actions** (backend services): API endpoints for advanced integrations (ApexCharts support included)
- **Custom Services**: API endpoints for advanced integrations (ApexCharts support included)
- **Diagnostic Sensors**: Monitor data freshness and availability
- **Reliable API Usage**: Uses only official Tibber [`priceInfo`](https://developer.tibber.com/docs/reference#priceinfo) and [`priceInfoRange`](https://developer.tibber.com/docs/reference#subscription) endpoints - no legacy APIs. Price ratings and statistics are calculated locally for maximum reliability and future-proofing.
@ -94,7 +79,7 @@ This will guide you through:
- Configure additional sensors in **Settings****Devices & Services****Tibber Price Information & Ratings** → **Entities**
- Use sensors in automations, dashboards, and scripts
📖 **[Full Installation Guide →](https://jpawlowski.github.io/hass.tibber_prices/user/installation)**
📖 **[Full Installation Guide →](docs/user/installation.md)**
## 📊 Available Entities
@ -102,8 +87,6 @@ The integration provides **30+ sensors** across different categories. Key sensor
> **Rich Sensor Attributes**: All sensors include extensive attributes with timestamps, context data, and detailed explanations. Enable **Extended Descriptions** in the integration options to add `long_description` and `usage_tips` attributes to every sensor, providing in-context documentation directly in Home Assistant's UI.
**[📋 Complete Sensor Reference](https://jpawlowski.github.io/hass.tibber_prices/user/sensors)** - Full list with descriptions and attributes
### Core Price Sensors (Enabled by Default)
| Entity | Description |
@ -146,8 +129,8 @@ The integration provides **30+ sensors** across different categories. Key sensor
| Entity | Description |
| ------------------------- | ----------------------------------------------------------------------------------------- |
| Peak Price Period | ON when in a detected peak price period ([how it works](https://jpawlowski.github.io/hass.tibber_prices/user/period-calculation)) |
| Best Price Period | ON when in a detected best price period ([how it works](https://jpawlowski.github.io/hass.tibber_prices/user/period-calculation)) |
| Peak Price Period | ON when in a detected peak price period ([how it works](docs/user/period-calculation.md)) |
| Best Price Period | ON when in a detected best price period ([how it works](docs/user/period-calculation.md)) |
| Tibber API Connection | Connection status to Tibber API |
| Tomorrow's Data Available | Whether tomorrow's price data is available |
@ -165,15 +148,13 @@ The following sensors are available but disabled by default. Enable them in `Set
- **Previous Interval Price** & **Previous Interval Price Level**: Historical data for the last 15-minute interval
- **Previous Interval Price Rating**: Rating for the previous interval
- **Trailing 24h Average Price**: Average of the past 24 hours from now
- **Trailing 24h Minimum/Maximum Price**: Min/max in the past 24 hours
- **Trailing 24h Minimum/Maximum Price**: Min/max in the past 24 hours
> **Note**: Currency display is configurable during setup. Choose between:
> - **Base currency** (€/kWh, kr/kWh) - decimal values, differences visible from 3rd-4th decimal
> - **Subunit** (ct/kWh, øre/kWh) - larger values, differences visible from 1st decimal
>
> Smart defaults: EUR → subunit (German/Dutch preference), NOK/SEK/DKK → base (Scandinavian preference). Supported currencies: EUR, NOK, SEK, DKK, USD, GBP.
> **Note**: All monetary sensors use minor currency units (ct/kWh, øre/kWh, ¢/kWh, p/kWh) automatically based on your Tibber account's currency. Supported: EUR, NOK, SEK, DKK, USD, GBP.
## Automation Examples> **Note:** See the [full automation examples guide](https://jpawlowski.github.io/hass.tibber_prices/user/automation-examples) for more advanced recipes.
## Automation Examples
> **Note:** See the [full automation examples guide](docs/user/automation-examples.md) for more advanced recipes.
### Run Appliances During Cheap Hours
@ -196,7 +177,7 @@ automation:
entity_id: switch.dishwasher
```
> **Learn more:** The [period calculation guide](https://jpawlowski.github.io/hass.tibber_prices/user/period-calculation) explains how Best/Peak Price periods are identified and how you can configure filters (flexibility, minimum distance from average, price level filters with gap tolerance).
> **Learn more:** The [period calculation guide](docs/user/period-calculation.md) explains how Best/Peak Price periods are identified and how you can configure filters (flexibility, minimum distance from average, price level filters with gap tolerance).
### Notify on Extremely High Prices
@ -284,9 +265,8 @@ automation:
### Currency or units showing incorrectly
- Currency is automatically detected from your Tibber account
- Display mode (base currency vs. subunit) can be configured in integration options: `Settings > Devices & Services > Tibber Price Information & Ratings > Configure`
- Supported currencies: EUR, NOK, SEK, DKK, USD, and GBP
- Smart defaults apply: EUR users get subunit (ct), Scandinavian users get base currency (kr)
- The integration supports EUR, NOK, SEK, DKK, USD, and GBP with appropriate minor units
- Enable/disable major vs. minor unit sensors in `Settings > Devices & Services > Tibber Price Information & Ratings > Entities`
## Advanced Features
@ -326,47 +306,34 @@ template:
Price at {{ timestamp }}: {{ price }} ct/kWh
```
📖 **[View all sensors and attributes →](https://jpawlowski.github.io/hass.tibber_prices/user/sensors)**
📖 **[View all sensors and attributes →](docs/user/sensors.md)**
### Dynamic Icons & Visual Indicators
### Custom Services
All sensors feature dynamic icons that change based on price levels, providing instant visual feedback in your dashboards.
The integration provides custom services for advanced use cases:
<img src="docs/user/static/img/entities-overview.jpg" width="400" alt="Entity list showing dynamic icons for different price states">
_Dynamic icons adapt to price levels, trends, and period states - showing CHEAP prices, FALLING trend, and active Best Price Period_
📖 **[Dynamic Icons Guide →](https://jpawlowski.github.io/hass.tibber_prices/user/dynamic-icons)** | **[Icon Colors Guide →](https://jpawlowski.github.io/hass.tibber_prices/user/icon-colors)**
### Custom Actions
The integration provides custom actions (they still appear as services under the hood) for advanced use cases. These actions show up in Home Assistant under **Developer Tools → Actions**.
- `tibber_prices.get_chartdata` - Get price data in chart-friendly formats for any visualization card
- `tibber_prices.get_price` - Fetch price data for specific days/times
- `tibber_prices.get_apexcharts_data` - Get formatted data for ApexCharts cards
- `tibber_prices.get_apexcharts_yaml` - Generate complete ApexCharts configurations
- `tibber_prices.refresh_user_data` - Manually refresh account information
📖 **[Action documentation and examples →](https://jpawlowski.github.io/hass.tibber_prices/user/actions)**
📖 **[Service documentation and examples →](docs/user/services.md)**
### Chart Visualizations (Optional)
### ApexCharts Integration
The integration includes built-in support for creating price visualization cards with automatic Y-axis scaling and color-coded series.
The integration includes built-in support for creating beautiful price visualization cards. Use the `get_apexcharts_yaml` service to generate card configurations automatically.
<img src="docs/user/static/img/charts/rolling-window.jpg" width="600" alt="Example: Dynamic 48h rolling window chart">
_Optional: Dynamic 48h chart with automatic Y-axis scaling - generated via `get_apexcharts_yaml` action_
📖 **[Chart examples and setup guide →](https://jpawlowski.github.io/hass.tibber_prices/user/chart-examples)**
📖 **[ApexCharts examples →](docs/user/automation-examples.md#apexcharts-cards)**
## 🤝 Contributing
Contributions are welcome! Please read the [Contributing Guidelines](CONTRIBUTING.md) and [Developer Documentation](https://jpawlowski.github.io/hass.tibber_prices/developer/) before submitting pull requests.
Contributions are welcome! Please read the [Contributing Guidelines](CONTRIBUTING.md) and [Developer Guide](docs/development/) before submitting pull requests.
### For Contributors
- **[Developer Setup](https://jpawlowski.github.io/hass.tibber_prices/developer/setup)** - Get started with DevContainer
- **[Architecture Guide](https://jpawlowski.github.io/hass.tibber_prices/developer/architecture)** - Understand the codebase
- **[Release Management](https://jpawlowski.github.io/hass.tibber_prices/developer/release-management)** - Release process and versioning
- **[Developer Setup](docs/development/setup.md)** - Get started with DevContainer
- **[Architecture Guide](docs/development/architecture.md)** - Understand the codebase
- **[Release Management](docs/development/release-management.md)** - Release process and versioning
## 🤖 Development Note

View file

@ -25,49 +25,8 @@ script:
scene:
energy:
# https://www.home-assistant.io/integrations/logger/
logger:
default: info
logs:
# Main integration logger - applies to ALL sub-loggers by default
custom_components.tibber_prices: debug
# Reduce verbosity for details loggers (change to 'debug' for deep debugging)
# API client details (raw requests/responses - very verbose!)
custom_components.tibber_prices.api.client.details: info
# Period calculation details (all set to 'info' by default, change to 'debug' as needed):
# Relaxation strategy details (flex levels, per-day results)
custom_components.tibber_prices.coordinator.period_handlers.relaxation.details: info
# Filter statistics and criteria checks
custom_components.tibber_prices.coordinator.period_handlers.period_building.details: info
# Outlier/spike detection details
custom_components.tibber_prices.coordinator.period_handlers.outlier_filtering.details: info
# Period overlap resolution details
custom_components.tibber_prices.coordinator.period_handlers.period_overlap.details: info
# Outlier flex capping
custom_components.tibber_prices.coordinator.period_handlers.core.details: info
# Level filtering details (min_distance scaling)
custom_components.tibber_prices.coordinator.period_handlers.level_filtering.details: info
# Interval pool details (cache operations, GC):
# Cache lookup/miss, gap detection, fetch group additions
custom_components.tibber_prices.interval_pool.manager.details: info
# Garbage collection details (eviction, dead interval cleanup)
custom_components.tibber_prices.interval_pool.garbage_collector.details: info
# Gap detection and API fetching details
custom_components.tibber_prices.interval_pool.fetcher.details: info
# API endpoint routing decisions
custom_components.tibber_prices.interval_pool.routing.details: info
# Cache fetch group operations
custom_components.tibber_prices.interval_pool.cache.details: info
# Index rebuild operations
custom_components.tibber_prices.interval_pool.index.details: info
# Storage save operations
custom_components.tibber_prices.interval_pool.storage.details: info
# API helpers details (response validation):
# Data emptiness checks, structure validation
custom_components.tibber_prices.api.helpers.details: info

View file

@ -7,23 +7,16 @@ https://github.com/jpawlowski/hass.tibber_prices
from __future__ import annotations
from typing import TYPE_CHECKING, Any
from typing import TYPE_CHECKING
import voluptuous as vol
from homeassistant.config_entries import ConfigEntry, ConfigEntryState
from homeassistant.config_entries import ConfigEntryState
from homeassistant.const import CONF_ACCESS_TOKEN, Platform
from homeassistant.exceptions import ConfigEntryAuthFailed
from homeassistant.helpers.aiohttp_client import async_get_clientsession
from homeassistant.helpers.storage import Store
from homeassistant.loader import async_get_loaded_integration
from .api import TibberPricesApiClient
from .const import (
CONF_CURRENCY_DISPLAY_MODE,
DATA_CHART_CONFIG,
DATA_CHART_METADATA_CONFIG,
DISPLAY_MODE_SUBUNIT,
DOMAIN,
LOGGER,
async_load_standard_translations,
@ -31,12 +24,6 @@ from .const import (
)
from .coordinator import STORAGE_VERSION, TibberPricesDataUpdateCoordinator
from .data import TibberPricesData
from .interval_pool import (
TibberPricesIntervalPool,
async_load_pool_state,
async_remove_pool_storage,
async_save_pool_state,
)
from .services import async_setup_services
if TYPE_CHECKING:
@ -47,142 +34,8 @@ if TYPE_CHECKING:
PLATFORMS: list[Platform] = [
Platform.SENSOR,
Platform.BINARY_SENSOR,
Platform.NUMBER,
Platform.SWITCH,
]
# Configuration schema for configuration.yaml
CONFIG_SCHEMA = vol.Schema(
{
DOMAIN: vol.Schema(
{
vol.Optional("chart_export"): vol.Schema(
{
vol.Optional("day"): vol.All(vol.Any(str, list), vol.Coerce(list)),
vol.Optional("resolution"): str,
vol.Optional("output_format"): str,
vol.Optional("subunit_currency"): bool,
vol.Optional("round_decimals"): vol.All(int, vol.Range(min=0, max=10)),
vol.Optional("include_level"): bool,
vol.Optional("include_rating_level"): bool,
vol.Optional("include_average"): bool,
vol.Optional("level_filter"): vol.All(vol.Any(str, list), vol.Coerce(list)),
vol.Optional("rating_level_filter"): vol.All(vol.Any(str, list), vol.Coerce(list)),
vol.Optional("period_filter"): str,
vol.Optional("insert_nulls"): str,
vol.Optional("add_trailing_null"): bool,
vol.Optional("array_fields"): str,
vol.Optional("start_time_field"): str,
vol.Optional("end_time_field"): str,
vol.Optional("price_field"): str,
vol.Optional("level_field"): str,
vol.Optional("rating_level_field"): str,
vol.Optional("average_field"): str,
vol.Optional("data_key"): str,
}
),
}
),
},
extra=vol.ALLOW_EXTRA,
)
async def async_setup(hass: HomeAssistant, config: dict[str, Any]) -> bool:
"""Set up the Tibber Prices component from configuration.yaml."""
# Store chart export configuration in hass.data for sensor access
if DOMAIN not in hass.data:
hass.data[DOMAIN] = {}
# Extract chart_export config if present
domain_config = config.get(DOMAIN, {})
chart_config = domain_config.get("chart_export", {})
if chart_config:
LOGGER.debug("Loaded chart_export configuration from configuration.yaml")
hass.data[DOMAIN][DATA_CHART_CONFIG] = chart_config
else:
LOGGER.debug("No chart_export configuration found in configuration.yaml")
hass.data[DOMAIN][DATA_CHART_CONFIG] = {}
# Extract chart_metadata config if present
chart_metadata_config = domain_config.get("chart_metadata", {})
if chart_metadata_config:
LOGGER.debug("Loaded chart_metadata configuration from configuration.yaml")
hass.data[DOMAIN][DATA_CHART_METADATA_CONFIG] = chart_metadata_config
else:
LOGGER.debug("No chart_metadata configuration found in configuration.yaml")
hass.data[DOMAIN][DATA_CHART_METADATA_CONFIG] = {}
return True
async def _migrate_config_options(hass: HomeAssistant, entry: ConfigEntry) -> None:
"""
Migrate config options for backward compatibility.
This ensures existing configs get sensible defaults when new options are added.
Runs automatically on integration startup.
"""
migration_performed = False
migrated = dict(entry.options)
# Migration: Set currency_display_mode to subunit for legacy configs
# New configs (created after v1.1.0) get currency-appropriate defaults via get_default_options().
# This migration preserves legacy behavior where all prices were in subunit currency (cents/øre).
# Only runs for old config entries that don't have this option explicitly set.
if CONF_CURRENCY_DISPLAY_MODE not in migrated:
migrated[CONF_CURRENCY_DISPLAY_MODE] = DISPLAY_MODE_SUBUNIT
migration_performed = True
LOGGER.info(
"[%s] Migrated legacy config: Set currency_display_mode=%s (preserves pre-v1.1.0 behavior)",
entry.title,
DISPLAY_MODE_SUBUNIT,
)
# Save migrated options if any changes were made
if migration_performed:
hass.config_entries.async_update_entry(entry, options=migrated)
LOGGER.debug("[%s] Config migration completed", entry.title)
def _get_access_token(hass: HomeAssistant, entry: ConfigEntry) -> str:
"""
Get access token from entry or parent entry.
For parent entries, the token is stored in entry.data.
For subentries, we need to find the parent entry and get its token.
Args:
hass: HomeAssistant instance
entry: Config entry (parent or subentry)
Returns:
Access token string
Raises:
ConfigEntryAuthFailed: If no access token found
"""
# Try to get token from this entry (works for parent)
if CONF_ACCESS_TOKEN in entry.data:
return entry.data[CONF_ACCESS_TOKEN]
# This is a subentry, find parent entry
# Parent entry is the one without subentries in its data structure
# and has the same domain
for potential_parent in hass.config_entries.async_entries(DOMAIN):
# Parent has ACCESS_TOKEN and is not the current entry
if potential_parent.entry_id != entry.entry_id and CONF_ACCESS_TOKEN in potential_parent.data:
# Check if this entry is actually a subentry of this parent
# (HA Core manages this relationship internally)
return potential_parent.data[CONF_ACCESS_TOKEN]
# No token found anywhere
msg = f"No access token found for entry {entry.entry_id}"
raise ConfigEntryAuthFailed(msg)
# https://developers.home-assistant.io/docs/config_entries_index/#setting-up-an-entry
async def async_setup_entry(
@ -191,10 +44,6 @@ async def async_setup_entry(
) -> bool:
"""Set up this integration using UI."""
LOGGER.debug(f"[tibber_prices] async_setup_entry called for entry_id={entry.entry_id}")
# Migrate config options if needed (e.g., set default currency display mode for existing configs)
await _migrate_config_options(hass, entry)
# Preload translations to populate the cache
await async_load_translations(hass, "en")
await async_load_standard_translations(hass, "en")
@ -209,78 +58,26 @@ async def async_setup_entry(
integration = async_get_loaded_integration(hass, entry.domain)
# Get access token (from this entry if parent, from parent if subentry)
access_token = _get_access_token(hass, entry)
# Create API client
api_client = TibberPricesApiClient(
access_token=access_token,
session=async_get_clientsession(hass),
version=str(integration.version) if integration.version else "unknown",
)
# Get home_id from config entry (required for single-home pool architecture)
home_id = entry.data.get("home_id")
if not home_id:
msg = f"[{entry.title}] Config entry missing home_id (required for interval pool)"
raise ConfigEntryAuthFailed(msg)
# Create or load interval pool for this config entry (single-home architecture)
pool_state = await async_load_pool_state(hass, entry.entry_id)
if pool_state:
interval_pool = TibberPricesIntervalPool.from_dict(
pool_state,
api=api_client,
hass=hass,
entry_id=entry.entry_id,
)
if interval_pool is None:
# Old multi-home format or corrupted → create new pool
LOGGER.info(
"[%s] Interval pool storage invalid/corrupted, creating new pool (will rebuild from API)",
entry.title,
)
interval_pool = TibberPricesIntervalPool(
home_id=home_id,
api=api_client,
hass=hass,
entry_id=entry.entry_id,
)
else:
LOGGER.debug("[%s] Interval pool restored from storage (auto-save enabled)", entry.title)
else:
interval_pool = TibberPricesIntervalPool(
home_id=home_id,
api=api_client,
hass=hass,
entry_id=entry.entry_id,
)
LOGGER.debug("[%s] Created new interval pool (auto-save enabled)", entry.title)
coordinator = TibberPricesDataUpdateCoordinator(
hass=hass,
config_entry=entry,
api_client=api_client,
interval_pool=interval_pool,
version=str(integration.version) if integration.version else "unknown",
)
# CRITICAL: Load cache BEFORE first refresh to ensure user_data is available
# for metadata sensors (grid_company, estimated_annual_consumption, etc.)
# This prevents sensors from being marked as "unavailable" on first setup
await coordinator.load_cache()
entry.runtime_data = TibberPricesData(
client=api_client,
client=TibberPricesApiClient(
access_token=entry.data[CONF_ACCESS_TOKEN],
session=async_get_clientsession(hass),
version=str(integration.version) if integration.version else "unknown",
),
integration=integration,
coordinator=coordinator,
interval_pool=interval_pool,
)
# https://developers.home-assistant.io/docs/integration_fetching_data#coordinated-single-api-poll-for-data-for-all-entities
if entry.state == ConfigEntryState.SETUP_IN_PROGRESS:
await coordinator.async_config_entry_first_refresh()
# Note: Options update listener is registered in coordinator.__init__
# (handles cache invalidation + refresh without full reload)
entry.async_on_unload(entry.add_update_listener(async_reload_entry))
else:
await coordinator.async_refresh()
@ -294,15 +91,6 @@ async def async_unload_entry(
entry: TibberPricesConfigEntry,
) -> bool:
"""Unload a config entry."""
# Save interval pool state before unloading
if entry.runtime_data is not None and entry.runtime_data.interval_pool is not None:
pool_state = entry.runtime_data.interval_pool.to_dict()
await async_save_pool_state(hass, entry.entry_id, pool_state)
LOGGER.debug("[%s] Interval pool state saved on unload", entry.title)
# Shutdown interval pool (cancels background tasks)
await entry.runtime_data.interval_pool.async_shutdown()
unload_ok = await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
if unload_ok and entry.runtime_data is not None:
@ -311,7 +99,8 @@ async def async_unload_entry(
# Unregister services if this was the last config entry
if not hass.config_entries.async_entries(DOMAIN):
for service in [
"get_chartdata",
"get_price",
"get_apexcharts_data",
"get_apexcharts_yaml",
"refresh_user_data",
]:
@ -326,15 +115,10 @@ async def async_remove_entry(
entry: TibberPricesConfigEntry,
) -> None:
"""Handle removal of an entry."""
# Remove coordinator cache storage
if storage := Store(hass, STORAGE_VERSION, f"{DOMAIN}.{entry.entry_id}"):
LOGGER.debug(f"[tibber_prices] async_remove_entry removing cache store for entry_id={entry.entry_id}")
await storage.async_remove()
# Remove interval pool storage
await async_remove_pool_storage(hass, entry.entry_id)
LOGGER.debug(f"[tibber_prices] async_remove_entry removed interval pool storage for entry_id={entry.entry_id}")
async def async_reload_entry(
hass: HomeAssistant,

View file

@ -3,17 +3,15 @@
from __future__ import annotations
import asyncio
import base64
import logging
import re
import socket
from datetime import datetime, timedelta
from typing import TYPE_CHECKING, Any
from zoneinfo import ZoneInfo
from datetime import timedelta
from typing import Any
import aiohttp
from homeassistant.util import dt as dt_utils
from homeassistant.util import dt as dt_util
from .exceptions import (
TibberPricesApiClientAuthenticationError,
@ -23,17 +21,14 @@ from .exceptions import (
)
from .helpers import (
flatten_price_info,
flatten_price_rating,
prepare_headers,
verify_graphql_response,
verify_response_or_raise,
)
from .queries import TibberPricesQueryType
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator.time_service import TibberPricesTimeService
from .queries import QueryType
_LOGGER = logging.getLogger(__name__)
_LOGGER_API_DETAILS = logging.getLogger(__name__ + ".details")
class TibberPricesApiClient:
@ -50,8 +45,7 @@ class TibberPricesApiClient:
self._session = session
self._version = version
self._request_semaphore = asyncio.Semaphore(2) # Max 2 concurrent requests
self.time: TibberPricesTimeService | None = None # Set externally by coordinator (optional during config flow)
self._last_request_time = None # Set on first request
self._last_request_time = dt_util.now()
self._min_request_interval = timedelta(seconds=1) # Min 1 second between requests
self._max_retries = 5
self._retry_delay = 2 # Base retry delay in seconds
@ -134,540 +128,201 @@ class TibberPricesApiClient:
}
"""
},
query_type=TibberPricesQueryType.USER,
query_type=QueryType.USER,
)
async def async_get_price_info_for_range(
self,
home_id: str,
user_data: dict[str, Any],
start_time: datetime,
end_time: datetime,
) -> dict:
async def async_get_price_info(self, home_ids: set[str]) -> dict:
"""
Get price info for a specific time range with automatic routing.
This is a convenience wrapper around interval_pool.get_price_intervals_for_range().
Get price info data in flat format for specified homes.
Args:
home_id: Home ID to fetch price data for.
user_data: User data dict containing home metadata (including timezone).
start_time: Start of the range (inclusive, timezone-aware).
end_time: End of the range (exclusive, timezone-aware).
home_ids: Set of home IDs to fetch data for.
Returns:
Dict with "home_id" and "price_info" (list of intervals).
Raises:
TibberPricesApiClientError: If arguments invalid or requests fail.
Dictionary with homes data keyed by home_id.
"""
# Import here to avoid circular dependency (interval_pool imports TibberPricesApiClient)
from custom_components.tibber_prices.interval_pool import ( # noqa: PLC0415
get_price_intervals_for_range,
)
return await self._get_price_info_for_specific_homes(home_ids)
price_info = await get_price_intervals_for_range(
api_client=self,
home_id=home_id,
user_data=user_data,
start_time=start_time,
end_time=end_time,
)
async def _get_price_info_for_specific_homes(self, home_ids: set[str]) -> dict:
"""Get price info for specific homes using GraphQL aliases."""
if not home_ids:
return {"homes": {}}
return {
"home_id": home_id,
"price_info": price_info,
}
async def async_get_price_info(self, home_id: str, user_data: dict[str, Any]) -> dict:
"""
Get price info for a single home.
Uses timezone-aware cursor calculation based on the home's actual timezone
from Tibber API (not HA system timezone). This ensures correct "day before yesterday
midnight" calculation for homes in different timezones.
Args:
home_id: Home ID to fetch price data for.
user_data: User data dict containing home metadata (including timezone).
REQUIRED - must be fetched before calling this method.
Returns:
Dict with "home_id", "price_info", and other home data.
Raises:
TibberPricesApiClientError: If TimeService not initialized or user_data missing.
"""
if not self.time:
msg = "TimeService not initialized - required for price info processing"
raise TibberPricesApiClientError(msg)
if not user_data:
msg = "User data required for timezone-aware price fetching - fetch user data first"
raise TibberPricesApiClientError(msg)
if not home_id:
msg = "Home ID is required"
raise TibberPricesApiClientError(msg)
# Build home_id -> timezone mapping from user_data
home_timezones = self._extract_home_timezones(user_data)
# Get timezone for this home (fallback to HA system timezone)
home_tz = home_timezones.get(home_id)
# Calculate cursor: day before yesterday midnight in home's timezone
cursor = self._calculate_cursor_for_home(home_tz)
# Simple single-home query (no alias needed)
query = f"""
{{viewer{{
home(id: "{home_id}") {{
# Build query with aliases for each home
# Example: home1: home(id: "abc") { ... }
home_queries = []
for idx, home_id in enumerate(sorted(home_ids)):
alias = f"home{idx}"
home_query = f"""
{alias}: home(id: "{home_id}") {{
id
consumption(resolution:DAILY,last:1) {{
pageInfo{{currency}}
}}
currentSubscription {{
priceInfoRange(resolution:QUARTER_HOURLY, first:192, after: "{cursor}") {{
pageInfo{{ count }}
priceInfoRange(resolution:QUARTER_HOURLY,last:192) {{
edges{{node{{
startsAt total level
startsAt total energy tax level
}}}}
}}
priceInfo(resolution:QUARTER_HOURLY) {{
today{{startsAt total level}}
tomorrow{{startsAt total level}}
today{{startsAt total energy tax level}}
tomorrow{{startsAt total energy tax level}}
}}
}}
}}
}}}}
"""
"""
home_queries.append(home_query)
_LOGGER.debug("Fetching price info for home %s", home_id)
query = "{viewer{" + "".join(home_queries) + "}}"
_LOGGER.debug("Fetching price info for %d specific home(s)", len(home_ids))
data = await self._api_wrapper(
data={"query": query},
query_type=TibberPricesQueryType.PRICE_INFO,
query_type=QueryType.PRICE_INFO,
)
# Parse response
# Parse aliased response
viewer = data.get("viewer", {})
home = viewer.get("home")
homes_data = {}
if not home:
msg = f"Home {home_id} not found in API response"
_LOGGER.warning(msg)
return {"home_id": home_id, "price_info": []}
for idx, home_id in enumerate(sorted(home_ids)):
alias = f"home{idx}"
home = viewer.get(alias)
if "currentSubscription" in home and home["currentSubscription"] is not None:
price_info = flatten_price_info(home["currentSubscription"])
else:
_LOGGER.warning(
"Home %s has no active subscription - price data will be unavailable",
home_id,
)
price_info = []
if not home:
_LOGGER.debug("Home %s not found in API response", home_id)
homes_data[home_id] = {}
continue
return {
"home_id": home_id,
"price_info": price_info,
}
if "currentSubscription" in home and home["currentSubscription"] is not None:
# Extract currency from consumption data if available
currency = None
if home.get("consumption"):
page_info = home["consumption"].get("pageInfo")
if page_info:
currency = page_info.get("currency")
async def async_get_price_info_range(
self,
home_id: str,
user_data: dict[str, Any],
start_time: datetime,
end_time: datetime,
) -> dict:
"""
Get historical price info for a specific time range using priceInfoRange endpoint.
Uses the priceInfoRange GraphQL endpoint for flexible historical data queries.
Intended for intervals BEFORE "day before yesterday midnight" (outside PRICE_INFO scope).
Automatically handles API pagination if Tibber limits batch size.
Args:
home_id: Home ID to fetch price data for.
user_data: User data dict containing home metadata (including timezone).
start_time: Start of the range (inclusive, timezone-aware).
end_time: End of the range (exclusive, timezone-aware).
Returns:
Dict with "home_id" and "price_info" (list of intervals).
Raises:
TibberPricesApiClientError: If arguments invalid or request fails.
"""
if not user_data:
msg = "User data required for timezone-aware price fetching - fetch user data first"
raise TibberPricesApiClientError(msg)
if not home_id:
msg = "Home ID is required"
raise TibberPricesApiClientError(msg)
if start_time >= end_time:
msg = f"Invalid time range: start_time ({start_time}) must be before end_time ({end_time})"
raise TibberPricesApiClientError(msg)
_LOGGER_API_DETAILS.debug(
"fetch_price_info_range called with: start_time=%s (type=%s, tzinfo=%s), end_time=%s (type=%s, tzinfo=%s)",
start_time,
type(start_time),
start_time.tzinfo,
end_time,
type(end_time),
end_time.tzinfo,
)
# Calculate cursor and interval count
start_cursor = self._encode_cursor(start_time)
interval_count = self._calculate_interval_count(start_time, end_time)
_LOGGER_API_DETAILS.debug(
"Calculated cursor for range: start_time=%s, cursor_time=%s, encoded=%s",
start_time,
start_time,
start_cursor,
)
# Fetch all intervals with automatic paging
price_info = await self._fetch_price_info_with_paging(
home_id=home_id,
start_cursor=start_cursor,
interval_count=interval_count,
)
return {
"home_id": home_id,
"price_info": price_info,
}
def _calculate_interval_count(self, start_time: datetime, end_time: datetime) -> int:
"""Calculate number of intervals needed based on date range."""
time_diff = end_time - start_time
resolution_change_date = datetime(2025, 10, 1, tzinfo=start_time.tzinfo)
if start_time < resolution_change_date:
# Pre-resolution-change: hourly intervals only
interval_count = int(time_diff.total_seconds() / 3600) # 3600s = 1h
_LOGGER_API_DETAILS.debug(
"Time range is pre-2025-10-01: expecting hourly intervals (count: %d)",
interval_count,
)
else:
# Post-resolution-change: quarter-hourly intervals
interval_count = int(time_diff.total_seconds() / 900) # 900s = 15min
_LOGGER_API_DETAILS.debug(
"Time range is post-2025-10-01: expecting quarter-hourly intervals (count: %d)",
interval_count,
)
return interval_count
async def _fetch_price_info_with_paging(
self,
home_id: str,
start_cursor: str,
interval_count: int,
) -> list[dict[str, Any]]:
"""
Fetch price info with automatic pagination if API limits batch size.
GraphQL Cursor Pagination:
- endCursor points to the last returned element (inclusive)
- Use 'after: endCursor' to get elements AFTER that cursor
- If count < requested, more pages available
Args:
home_id: Home ID to fetch price data for.
start_cursor: Base64-encoded start cursor.
interval_count: Total number of intervals to fetch.
Returns:
List of all price interval dicts across all pages.
"""
price_info = []
remaining_intervals = interval_count
cursor = start_cursor
page = 0
while remaining_intervals > 0:
page += 1
# Fetch one page
page_data = await self._fetch_single_page(
home_id=home_id,
cursor=cursor,
requested_count=remaining_intervals,
page=page,
)
if not page_data:
break
# Extract intervals and pagination info
page_intervals = page_data["intervals"]
returned_count = page_data["count"]
end_cursor = page_data["end_cursor"]
has_next_page = page_data.get("has_next_page", False)
price_info.extend(page_intervals)
_LOGGER_API_DETAILS.debug(
"Page %d: Received %d intervals for home %s (total so far: %d/%d, endCursor=%s, hasNextPage=%s)",
page,
returned_count,
home_id,
len(price_info),
interval_count,
end_cursor,
has_next_page,
)
# Update remaining count
remaining_intervals -= returned_count
# Check if we need more pages
# Continue if: (1) we still need more intervals AND (2) API has more data
if remaining_intervals > 0 and end_cursor:
cursor = end_cursor
_LOGGER_API_DETAILS.debug(
"Still need %d more intervals - fetching next page with cursor %s",
remaining_intervals,
cursor,
homes_data[home_id] = flatten_price_info(
home["currentSubscription"],
currency,
)
else:
# Done: Either we have all intervals we need, or API has no more data
if remaining_intervals > 0:
_LOGGER.warning(
"API has no more data - received %d out of %d requested intervals (missing %d)",
len(price_info),
interval_count,
remaining_intervals,
)
else:
_LOGGER.debug(
"Pagination complete - received all %d requested intervals",
interval_count,
)
break
_LOGGER.debug(
"Home %s has no active subscription - price data will be unavailable",
home_id,
)
homes_data[home_id] = {}
_LOGGER_API_DETAILS.debug(
"Fetched %d total historical intervals for home %s across %d page(s)",
len(price_info),
home_id,
page,
)
return price_info
async def _fetch_single_page(
self,
home_id: str,
cursor: str,
requested_count: int,
page: int,
) -> dict[str, Any] | None:
"""
Fetch a single page of price intervals.
Args:
home_id: Home ID to fetch price data for.
cursor: Base64-encoded cursor for this page.
requested_count: Number of intervals to request.
page: Page number (for logging).
Returns:
Dict with "intervals", "count", and "end_cursor" keys, or None if no data.
"""
query = f"""
{{viewer{{
home(id: "{home_id}") {{
id
currentSubscription {{
priceInfoRange(resolution:QUARTER_HOURLY, first:{requested_count}, after: "{cursor}") {{
pageInfo{{
count
hasNextPage
startCursor
endCursor
}}
edges{{
cursor
node{{
startsAt total level
}}
}}
}}
}}
}}
}}}}
"""
_LOGGER_API_DETAILS.debug(
"Fetching historical price info for home %s (page %d): %d intervals from cursor %s",
home_id,
page,
requested_count,
cursor,
)
data["homes"] = homes_data
return data
async def async_get_daily_price_rating(self) -> dict:
"""Get daily price rating data in flat format for all homes."""
data = await self._api_wrapper(
data={"query": query},
query_type=TibberPricesQueryType.PRICE_INFO_RANGE,
data={
"query": """
{viewer{homes{id,currentSubscription{priceRating{
daily{
currency
entries{time total energy tax difference level}
}
}}}}}"""
},
query_type=QueryType.DAILY_RATING,
)
homes = data.get("viewer", {}).get("homes", [])
# Parse response
viewer = data.get("viewer", {})
home = viewer.get("home")
if not home:
_LOGGER.warning("Home %s not found in API response", home_id)
return None
if "currentSubscription" not in home or home["currentSubscription"] is None:
_LOGGER.warning("Home %s has no active subscription - price data will be unavailable", home_id)
return None
# Extract priceInfoRange data
subscription = home["currentSubscription"]
price_info_range = subscription.get("priceInfoRange", {})
page_info = price_info_range.get("pageInfo", {})
edges = price_info_range.get("edges", [])
# Flatten edges to interval list
intervals = [edge["node"] for edge in edges if "node" in edge]
return {
"intervals": intervals,
"count": page_info.get("count", len(intervals)),
"end_cursor": page_info.get("endCursor"),
"has_next_page": page_info.get("hasNextPage", False),
}
def _extract_home_timezones(self, user_data: dict[str, Any]) -> dict[str, str]:
"""
Extract home_id -> timezone mapping from user_data.
Args:
user_data: User data dict from async_get_viewer_details() (required).
Returns:
Dict mapping home_id to timezone string (e.g., "Europe/Oslo").
"""
home_timezones = {}
viewer = user_data.get("viewer", {})
homes = viewer.get("homes", [])
homes_data = {}
for home in homes:
home_id = home.get("id")
timezone = home.get("timeZone")
if home_id:
if "currentSubscription" in home and home["currentSubscription"] is not None:
homes_data[home_id] = flatten_price_rating(home["currentSubscription"])
else:
_LOGGER.debug(
"Home %s has no active subscription - daily rating data will be unavailable",
home_id,
)
homes_data[home_id] = {}
if home_id and timezone:
home_timezones[home_id] = timezone
_LOGGER_API_DETAILS.debug("Extracted timezone %s for home %s", timezone, home_id)
elif home_id:
_LOGGER.warning("Home %s has no timezone in user data, will use fallback", home_id)
data["homes"] = homes_data
return data
return home_timezones
async def async_get_hourly_price_rating(self) -> dict:
"""Get hourly price rating data in flat format for all homes."""
data = await self._api_wrapper(
data={
"query": """
{viewer{homes{id,currentSubscription{priceRating{
hourly{
currency
entries{time total energy tax difference level}
}
}}}}}"""
},
query_type=QueryType.HOURLY_RATING,
)
homes = data.get("viewer", {}).get("homes", [])
def _calculate_day_before_yesterday_midnight(self, home_timezone: str | None) -> datetime:
"""
Calculate day before yesterday midnight in home's timezone.
homes_data = {}
for home in homes:
home_id = home.get("id")
if home_id:
if "currentSubscription" in home and home["currentSubscription"] is not None:
homes_data[home_id] = flatten_price_rating(home["currentSubscription"])
else:
_LOGGER.debug(
"Home %s has no active subscription - hourly rating data will be unavailable",
home_id,
)
homes_data[home_id] = {}
CRITICAL: Uses REAL TIME (dt_utils.now()), NOT TimeService.now().
This ensures API boundary calculations are based on actual current time,
not simulated time from TimeService.
data["homes"] = homes_data
return data
Args:
home_timezone: Timezone string (e.g., "Europe/Oslo").
If None, falls back to HA system timezone.
async def async_get_monthly_price_rating(self) -> dict:
"""Get monthly price rating data in flat format for all homes."""
data = await self._api_wrapper(
data={
"query": """
{viewer{homes{id,currentSubscription{priceRating{
monthly{
currency
entries{time total energy tax difference level}
}
}}}}}"""
},
query_type=QueryType.MONTHLY_RATING,
)
homes = data.get("viewer", {}).get("homes", [])
Returns:
Timezone-aware datetime for day before yesterday midnight.
homes_data = {}
for home in homes:
home_id = home.get("id")
if home_id:
if "currentSubscription" in home and home["currentSubscription"] is not None:
homes_data[home_id] = flatten_price_rating(home["currentSubscription"])
else:
_LOGGER.debug(
"Home %s has no active subscription - monthly rating data will be unavailable",
home_id,
)
homes_data[home_id] = {}
"""
# Get current REAL time (not TimeService)
now = dt_utils.now()
# Convert to home's timezone or fallback to HA system timezone
if home_timezone:
try:
tz = ZoneInfo(home_timezone)
now_in_home_tz = now.astimezone(tz)
except (KeyError, ValueError, OSError) as error:
_LOGGER.warning(
"Invalid timezone %s (%s), falling back to HA system timezone",
home_timezone,
error,
)
now_in_home_tz = dt_utils.as_local(now)
else:
# Fallback to HA system timezone
now_in_home_tz = dt_utils.as_local(now)
# Calculate day before yesterday midnight
return (now_in_home_tz - timedelta(days=2)).replace(hour=0, minute=0, second=0, microsecond=0)
def _encode_cursor(self, timestamp: datetime) -> str:
"""
Encode a timestamp as base64 cursor for GraphQL API.
Args:
timestamp: Timezone-aware datetime to encode.
Returns:
Base64-encoded ISO timestamp string.
"""
iso_string = timestamp.isoformat()
return base64.b64encode(iso_string.encode()).decode()
def _parse_timestamp(self, timestamp_str: str) -> datetime:
"""
Parse ISO timestamp string to timezone-aware datetime.
Args:
timestamp_str: ISO format timestamp string.
Returns:
Timezone-aware datetime object.
"""
return dt_utils.parse_datetime(timestamp_str) or dt_utils.now()
def _calculate_cursor_for_home(self, home_timezone: str | None) -> str:
"""
Calculate cursor (day before yesterday midnight) for a home's timezone.
Convenience wrapper around _calculate_day_before_yesterday_midnight()
and _encode_cursor() for backward compatibility with existing code.
Args:
home_timezone: Timezone string (e.g., "Europe/Oslo", "America/New_York").
If None, falls back to HA system timezone.
Returns:
Base64-encoded ISO timestamp string for use as GraphQL cursor.
"""
day_before_yesterday_midnight = self._calculate_day_before_yesterday_midnight(home_timezone)
return self._encode_cursor(day_before_yesterday_midnight)
data["homes"] = homes_data
return data
async def _make_request(
self,
headers: dict[str, str],
data: dict,
query_type: TibberPricesQueryType,
query_type: QueryType,
) -> dict[str, Any]:
"""Make an API request with comprehensive error handling for network issues."""
_LOGGER_API_DETAILS.debug("Making API request with data: %s", data)
_LOGGER.debug("Making API request with data: %s", data)
try:
# More granular timeout configuration for better network failure handling
@ -687,7 +342,7 @@ class TibberPricesApiClient:
verify_response_or_raise(response)
response_json = await response.json()
_LOGGER_API_DETAILS.debug("Received API response: %s", response_json)
_LOGGER.debug("Received API response: %s", response_json)
await verify_graphql_response(response_json, query_type)
@ -785,24 +440,21 @@ class TibberPricesApiClient:
self,
headers: dict[str, str],
data: dict,
query_type: TibberPricesQueryType,
query_type: QueryType,
) -> Any:
"""Handle a single API request with rate limiting."""
async with self._request_semaphore:
# Rate limiting: ensure minimum interval between requests
if self.time and self._last_request_time:
now = self.time.now()
time_since_last_request = now - self._last_request_time
if time_since_last_request < self._min_request_interval:
sleep_time = (self._min_request_interval - time_since_last_request).total_seconds()
_LOGGER_API_DETAILS.debug(
"Rate limiting: waiting %s seconds before next request",
sleep_time,
)
await asyncio.sleep(sleep_time)
now = dt_util.now()
time_since_last_request = now - self._last_request_time
if time_since_last_request < self._min_request_interval:
sleep_time = (self._min_request_interval - time_since_last_request).total_seconds()
_LOGGER.debug(
"Rate limiting: waiting %s seconds before next request",
sleep_time,
)
await asyncio.sleep(sleep_time)
if self.time:
self._last_request_time = self.time.now()
self._last_request_time = dt_util.now()
return await self._make_request(
headers,
data or {},
@ -841,18 +493,23 @@ class TibberPricesApiClient:
"""Handle retry logic for API-specific errors."""
error_msg = str(error)
# Non-retryable: Invalid queries, bad requests, empty data
# Empty data means API has no data for the requested range - retrying won't help
if "Invalid GraphQL query" in error_msg or "Bad request" in error_msg or "Empty data received" in error_msg:
# Non-retryable: Invalid queries
if "Invalid GraphQL query" in error_msg or "Bad request" in error_msg:
return False, 0
# Rate limits - only retry if server explicitly says so
# Rate limits - special handling with extracted delay
if "Rate limit exceeded" in error_msg or "rate limited" in error_msg.lower():
delay = self._extract_retry_delay(error, retry)
return True, delay
# Other API errors - not retryable (assume permanent issue)
return False, 0
# Empty data - retryable with capped exponential backoff
if "Empty data received" in error_msg:
delay = min(self._retry_delay * (2**retry), 60) # Cap at 60 seconds
return True, delay
# Other API errors - retryable with capped exponential backoff
delay = min(self._retry_delay * (2**retry), 30) # Cap at 30 seconds
return True, delay
def _extract_retry_delay(self, error: Exception, retry: int) -> int:
"""Extract retry delay from rate limit error or use exponential backoff."""
@ -884,26 +541,9 @@ class TibberPricesApiClient:
self,
data: dict | None = None,
headers: dict | None = None,
query_type: TibberPricesQueryType = TibberPricesQueryType.USER,
query_type: QueryType = QueryType.USER,
) -> Any:
"""
Get information from the API with rate limiting and retry logic.
Exception Handling Strategy:
- AuthenticationError: Immediate raise, triggers reauth flow
- PermissionError: Immediate raise, non-retryable
- CommunicationError: Retry with exponential backoff
- ApiClientError (Rate Limit): Retry with Retry-After delay
- ApiClientError (Other): Retry only if explicitly retryable
- Network errors (aiohttp.ClientError, socket.gaierror, TimeoutError):
Converted to CommunicationError and retried
Retry Logic:
- Max retries: 5 (configurable via _max_retries)
- Base delay: 2 seconds (exponential backoff: 2s, 4s, 8s, 16s, 32s)
- Rate limit delay: Uses Retry-After header or falls back to exponential
- Caps: 30s for network errors, 120s for rate limits, 300s for Retry-After
"""
"""Get information from the API with rate limiting and retry logic."""
headers = headers or prepare_headers(self._access_token, self._version)
last_error: Exception | None = None

View file

@ -3,14 +3,16 @@
from __future__ import annotations
import logging
from datetime import timedelta
from typing import TYPE_CHECKING
from homeassistant.const import __version__ as ha_version
from homeassistant.util import dt as dt_util
if TYPE_CHECKING:
import aiohttp
from .queries import TibberPricesQueryType
from .queries import QueryType
from .exceptions import (
TibberPricesApiClientAuthenticationError,
@ -19,85 +21,36 @@ from .exceptions import (
)
_LOGGER = logging.getLogger(__name__)
_LOGGER_DETAILS = logging.getLogger(__name__ + ".details")
HTTP_BAD_REQUEST = 400
HTTP_UNAUTHORIZED = 401
HTTP_FORBIDDEN = 403
HTTP_TOO_MANY_REQUESTS = 429
HTTP_INTERNAL_SERVER_ERROR = 500
HTTP_BAD_GATEWAY = 502
HTTP_SERVICE_UNAVAILABLE = 503
HTTP_GATEWAY_TIMEOUT = 504
def verify_response_or_raise(response: aiohttp.ClientResponse) -> None:
"""
Verify HTTP response and map to appropriate exceptions.
Error Mapping:
- 401 Unauthorized AuthenticationError (non-retryable)
- 403 Forbidden PermissionError (non-retryable)
- 429 Rate Limit ApiClientError with retry support
- 400 Bad Request ApiClientError (non-retryable, invalid query)
- 5xx Server Errors CommunicationError (retryable)
- Other errors Let aiohttp.raise_for_status() handle
"""
# Authentication failures - non-retryable
"""Verify that the response is valid."""
if response.status == HTTP_UNAUTHORIZED:
_LOGGER.error("Tibber API authentication failed - check access token")
raise TibberPricesApiClientAuthenticationError(TibberPricesApiClientAuthenticationError.INVALID_CREDENTIALS)
# Permission denied - non-retryable
if response.status == HTTP_FORBIDDEN:
_LOGGER.error("Tibber API access forbidden - insufficient permissions")
raise TibberPricesApiClientPermissionError(TibberPricesApiClientPermissionError.INSUFFICIENT_PERMISSIONS)
# Rate limiting - retryable with explicit delay
if response.status == HTTP_TOO_MANY_REQUESTS:
# Check for Retry-After header that Tibber might send
retry_after = response.headers.get("Retry-After", "unknown")
_LOGGER.warning("Tibber API rate limit exceeded - retry after %s seconds", retry_after)
raise TibberPricesApiClientError(TibberPricesApiClientError.RATE_LIMIT_ERROR.format(retry_after=retry_after))
# Bad request - non-retryable (invalid query)
if response.status == HTTP_BAD_REQUEST:
_LOGGER.error("Tibber API rejected request - likely invalid GraphQL query")
raise TibberPricesApiClientError(
TibberPricesApiClientError.INVALID_QUERY_ERROR.format(message="Bad request - likely invalid GraphQL query")
)
# Server errors 5xx - retryable (temporary server issues)
if response.status in (
HTTP_INTERNAL_SERVER_ERROR,
HTTP_BAD_GATEWAY,
HTTP_SERVICE_UNAVAILABLE,
HTTP_GATEWAY_TIMEOUT,
):
_LOGGER.warning(
"Tibber API server error %d - temporary issue, will retry",
response.status,
)
# Let this be caught as aiohttp.ClientResponseError in _api_wrapper
# where it's converted to CommunicationError with retry logic
response.raise_for_status()
# All other HTTP errors - let aiohttp handle
response.raise_for_status()
async def verify_graphql_response(response_json: dict, query_type: TibberPricesQueryType) -> None:
"""
Verify GraphQL response and map error codes to appropriate exceptions.
GraphQL Error Code Mapping:
- UNAUTHENTICATED AuthenticationError (triggers reauth flow)
- FORBIDDEN PermissionError (non-retryable)
- RATE_LIMITED/TOO_MANY_REQUESTS ApiClientError (retryable)
- VALIDATION_ERROR/GRAPHQL_VALIDATION_FAILED ApiClientError (non-retryable)
- Other codes Generic ApiClientError (with code in message)
- Empty data ApiClientError (non-retryable, API has no data)
"""
async def verify_graphql_response(response_json: dict, query_type: QueryType) -> None:
"""Verify the GraphQL response for errors and data completeness, including empty data."""
if "errors" in response_json:
errors = response_json["errors"]
if not errors:
@ -144,137 +97,14 @@ async def verify_graphql_response(response_json: dict, query_type: TibberPricesQ
TibberPricesApiClientError.GRAPHQL_ERROR.format(message="Response missing data object")
)
# Empty data check - validate response completeness
# This is NOT a retryable error - API simply has no data for the requested range
# Empty data check (for retry logic) - always check, regardless of query_type
if is_data_empty(response_json["data"], query_type.value):
_LOGGER_DETAILS.debug("Empty data detected for query_type: %s - API has no data available", query_type)
_LOGGER.debug("Empty data detected for query_type: %s", query_type)
raise TibberPricesApiClientError(
TibberPricesApiClientError.EMPTY_DATA_ERROR.format(query_type=query_type.value)
)
def _check_user_data_empty(data: dict) -> bool:
"""Check if user data is empty or incomplete."""
has_user_id = (
"viewer" in data
and isinstance(data["viewer"], dict)
and "userId" in data["viewer"]
and data["viewer"]["userId"] is not None
)
has_homes = (
"viewer" in data
and isinstance(data["viewer"], dict)
and "homes" in data["viewer"]
and isinstance(data["viewer"]["homes"], list)
and len(data["viewer"]["homes"]) > 0
)
is_empty = not has_user_id or not has_homes
_LOGGER_DETAILS.debug(
"Viewer check - has_user_id: %s, has_homes: %s, is_empty: %s",
has_user_id,
has_homes,
is_empty,
)
return is_empty
def _check_price_info_empty(data: dict) -> bool:
"""
Check if price_info data is empty or incomplete.
Note: Missing currentSubscription is VALID (home without active contract).
Only check for structural issues, not missing data that legitimately might not exist.
"""
viewer = data.get("viewer", {})
home_data = viewer.get("home")
if not home_data:
_LOGGER_DETAILS.debug("No home data found in price_info response")
return True
_LOGGER_DETAILS.debug("Checking price_info for single home")
# Missing currentSubscription is VALID - home has no active contract
# This is not an "empty data" error, it's a legitimate state
if "currentSubscription" not in home_data or home_data["currentSubscription"] is None:
_LOGGER_DETAILS.debug("No currentSubscription - home has no active contract (valid state)")
return False # NOT empty - this is expected for homes without subscription
subscription = home_data["currentSubscription"]
# Check priceInfoRange (yesterday data - optional, may not be available)
has_yesterday = (
"priceInfoRange" in subscription
and subscription["priceInfoRange"] is not None
and "edges" in subscription["priceInfoRange"]
and subscription["priceInfoRange"]["edges"]
)
# Check priceInfo for today's data (required if subscription exists)
has_price_info = "priceInfo" in subscription and subscription["priceInfo"] is not None
has_today = (
has_price_info
and "today" in subscription["priceInfo"]
and subscription["priceInfo"]["today"] is not None
and len(subscription["priceInfo"]["today"]) > 0
)
# Only require today's data - yesterday is optional
# If subscription exists but no today data, that's a structural problem
is_empty = not has_today
_LOGGER_DETAILS.debug(
"Price info check - priceInfoRange: %s, today: %s, is_empty: %s",
bool(has_yesterday),
bool(has_today),
is_empty,
)
return is_empty
def _check_price_info_range_empty(data: dict) -> bool:
"""
Check if price_info_range data is empty or incomplete.
For historical range queries, empty edges array is VALID (no data available
for that time range, e.g., too old). Only structural problems are errors.
"""
viewer = data.get("viewer", {})
home_data = viewer.get("home")
if not home_data:
_LOGGER_DETAILS.debug("No home data found in price_info_range response")
return True
subscription = home_data.get("currentSubscription")
if not subscription:
_LOGGER_DETAILS.debug("Missing currentSubscription in home")
return True
# For price_info_range, check if the structure exists
# Empty edges array is VALID (no data for that time range)
price_info_range = subscription.get("priceInfoRange")
if price_info_range is None:
_LOGGER_DETAILS.debug("Missing priceInfoRange in subscription")
return True
if "edges" not in price_info_range:
_LOGGER_DETAILS.debug("Missing edges key in priceInfoRange")
return True
edges = price_info_range["edges"]
if not isinstance(edges, list):
_LOGGER_DETAILS.debug("priceInfoRange edges is not a list")
return True
# Empty edges is VALID for historical queries (data not available)
_LOGGER_DETAILS.debug(
"Price info range check - structure valid, edge_count: %s (empty is OK for old data)",
len(edges),
)
return False # Structure is valid, even if edges is empty
def is_data_empty(data: dict, query_type: str) -> bool:
"""
Check if the response data is empty or incomplete.
@ -290,27 +120,126 @@ def is_data_empty(data: dict, query_type: str) -> bool:
- Must have today data
- tomorrow can be empty if we have valid historical and today data
For price info range:
- Must have priceInfoRange with edges
Used by interval pool for historical data fetching
For rating data:
- Must have thresholdPercentages
- Must have non-empty entries for the specific rating type
"""
_LOGGER_DETAILS.debug("Checking if data is empty for query_type %s", query_type)
_LOGGER.debug("Checking if data is empty for query_type %s", query_type)
is_empty = False
try:
if query_type == "user":
return _check_user_data_empty(data)
if query_type == "price_info":
return _check_price_info_empty(data)
if query_type == "price_info_range":
return _check_price_info_range_empty(data)
has_user_id = (
"viewer" in data
and isinstance(data["viewer"], dict)
and "userId" in data["viewer"]
and data["viewer"]["userId"] is not None
)
has_homes = (
"viewer" in data
and isinstance(data["viewer"], dict)
and "homes" in data["viewer"]
and isinstance(data["viewer"]["homes"], list)
and len(data["viewer"]["homes"]) > 0
)
is_empty = not has_user_id or not has_homes
_LOGGER.debug(
"Viewer check - has_user_id: %s, has_homes: %s, is_empty: %s",
has_user_id,
has_homes,
is_empty,
)
# Unknown query type
_LOGGER_DETAILS.debug("Unknown query type %s, treating as non-empty", query_type)
elif query_type == "price_info":
# Check for home aliases (home0, home1, etc.)
viewer = data.get("viewer", {})
home_aliases = [key for key in viewer if key.startswith("home") and key[4:].isdigit()]
if not home_aliases:
_LOGGER.debug("No home aliases found in price_info response")
is_empty = True
else:
# Check first home for valid data
_LOGGER.debug("Checking price_info with %d home(s)", len(home_aliases))
first_home = viewer.get(home_aliases[0])
if (
not first_home
or "currentSubscription" not in first_home
or first_home["currentSubscription"] is None
):
_LOGGER.debug("Missing currentSubscription in first home")
is_empty = True
else:
subscription = first_home["currentSubscription"]
# Check priceInfoRange (192 quarter-hourly intervals)
has_historical = (
"priceInfoRange" in subscription
and subscription["priceInfoRange"] is not None
and "edges" in subscription["priceInfoRange"]
and subscription["priceInfoRange"]["edges"]
)
# Check priceInfo for today's data
has_price_info = "priceInfo" in subscription and subscription["priceInfo"] is not None
has_today = (
has_price_info
and "today" in subscription["priceInfo"]
and subscription["priceInfo"]["today"] is not None
and len(subscription["priceInfo"]["today"]) > 0
)
# Data is empty if we don't have historical data or today's data
is_empty = not has_historical or not has_today
_LOGGER.debug(
"Price info check - priceInfoRange: %s, today: %s, is_empty: %s",
bool(has_historical),
bool(has_today),
is_empty,
)
elif query_type in ["daily", "hourly", "monthly"]:
# Check for homes existence and non-emptiness before accessing
if (
"viewer" not in data
or "homes" not in data["viewer"]
or not isinstance(data["viewer"]["homes"], list)
or len(data["viewer"]["homes"]) == 0
or "currentSubscription" not in data["viewer"]["homes"][0]
or data["viewer"]["homes"][0]["currentSubscription"] is None
or "priceRating" not in data["viewer"]["homes"][0]["currentSubscription"]
):
_LOGGER.debug("Missing homes/currentSubscription/priceRating in rating check")
is_empty = True
else:
rating = data["viewer"]["homes"][0]["currentSubscription"]["priceRating"]
# Check rating entries
has_entries = (
query_type in rating
and rating[query_type] is not None
and "entries" in rating[query_type]
and rating[query_type]["entries"] is not None
and len(rating[query_type]["entries"]) > 0
)
is_empty = not has_entries
_LOGGER.debug(
"%s rating check - entries count: %d, is_empty: %s",
query_type,
len(rating[query_type]["entries"]) if has_entries else 0,
is_empty,
)
else:
_LOGGER.debug("Unknown query type %s, treating as non-empty", query_type)
is_empty = False
except (KeyError, IndexError, TypeError) as error:
_LOGGER_DETAILS.debug("Error checking data emptiness: %s", error)
return True
else:
return False
_LOGGER.debug("Error checking data emptiness: %s", error)
is_empty = True
return is_empty
def prepare_headers(access_token: str, version: str) -> dict[str, str]:
@ -322,30 +251,23 @@ def prepare_headers(access_token: str, version: str) -> dict[str, str]:
}
def flatten_price_info(subscription: dict) -> list[dict]:
def flatten_price_info(subscription: dict, currency: str | None = None) -> dict:
"""
Transform and flatten priceInfo from full API data structure.
Returns a flat list of all price intervals ordered as:
[day_before_yesterday_prices, yesterday_prices, today_prices, tomorrow_prices]
priceInfoRange fetches 192 quarter-hourly intervals starting from the day before
yesterday midnight (2 days of historical data), which provides sufficient data
for calculating trailing 24h averages for all intervals including yesterday.
Args:
subscription: The currentSubscription dictionary from API response.
Returns:
A flat list containing all price dictionaries (startsAt, total, level).
Now handles priceInfoRange (192 quarter-hourly intervals) separately from
priceInfo (today and tomorrow data). Currency is stored as a separate attribute.
"""
# Use 'or {}' to handle None values (API may return None during maintenance)
price_info_range = subscription.get("priceInfoRange") or {}
price_info = subscription.get("priceInfo", {})
price_info_range = subscription.get("priceInfoRange", {})
# Transform priceInfoRange edges data (extract historical quarter-hourly prices)
# This contains 192 intervals (2 days) starting from day before yesterday midnight
historical_prices = []
# Get today and yesterday dates using Home Assistant's dt_util
today_local = dt_util.now().date()
yesterday_local = today_local - timedelta(days=1)
_LOGGER.debug("Processing data for yesterday's date: %s", yesterday_local)
# Transform priceInfoRange edges data (extract yesterday's quarter-hourly prices)
yesterday_prices = []
if "edges" in price_info_range:
edges = price_info_range["edges"]
@ -353,9 +275,49 @@ def flatten_price_info(subscription: dict) -> list[dict]:
if "node" not in edge:
_LOGGER.debug("Skipping edge without node: %s", edge)
continue
historical_prices.append(edge["node"])
# Return all intervals as a single flattened array
# Use 'or {}' to handle None values (API may return None during maintenance)
price_info = subscription.get("priceInfo") or {}
return historical_prices + (price_info.get("today") or []) + (price_info.get("tomorrow") or [])
price_data = edge["node"]
# Parse timestamp using dt_util for proper timezone handling
starts_at = dt_util.parse_datetime(price_data["startsAt"])
if starts_at is None:
_LOGGER.debug("Could not parse timestamp: %s", price_data["startsAt"])
continue
# Convert to local timezone
starts_at = dt_util.as_local(starts_at)
price_date = starts_at.date()
# Only include prices from yesterday
if price_date == yesterday_local:
yesterday_prices.append(price_data)
_LOGGER.debug("Found %d price entries for yesterday", len(yesterday_prices))
return {
"yesterday": yesterday_prices,
"today": price_info.get("today", []),
"tomorrow": price_info.get("tomorrow", []),
"currency": currency,
}
def flatten_price_rating(subscription: dict) -> dict:
"""Extract and flatten priceRating from subscription, including currency."""
price_rating = subscription.get("priceRating", {})
def extract_entries_and_currency(rating: dict) -> tuple[list, str | None]:
if rating is None:
return [], None
return rating.get("entries", []), rating.get("currency")
hourly_entries, hourly_currency = extract_entries_and_currency(price_rating.get("hourly"))
daily_entries, daily_currency = extract_entries_and_currency(price_rating.get("daily"))
monthly_entries, monthly_currency = extract_entries_and_currency(price_rating.get("monthly"))
# Prefer hourly, then daily, then monthly for top-level currency
currency = hourly_currency or daily_currency or monthly_currency
return {
"hourly": hourly_entries,
"daily": daily_entries,
"monthly": monthly_entries,
"currency": currency,
}

View file

@ -5,44 +5,11 @@ from __future__ import annotations
from enum import Enum
class TibberPricesQueryType(Enum):
"""
Types of queries that can be made to the API.
CRITICAL: Query type selection is dictated by Tibber's API design and caching strategy.
PRICE_INFO:
- Used for current day-relative data (day before yesterday/yesterday/today/tomorrow)
- API automatically determines "today" and "tomorrow" based on current time
- MUST be used when querying any data from these 4 days, even if you only need
specific intervals, because Tibber's API requires this endpoint for current data
- Provides the core dataset needed for live data, recent historical context
(important until tomorrow's data arrives), and tomorrow's forecast
- Tibber likely has optimized caching for this frequently-accessed data range
- Boundary: FROM "day before yesterday midnight" (real time) onwards
PRICE_INFO_RANGE:
- Used for historical data older than day before yesterday
- Allows flexible date range queries with cursor-based pagination
- Required for any intervals beyond the 4-day window of PRICE_INFO
- Use this for historical analysis, comparisons, or trend calculations
- Boundary: BEFORE "day before yesterday midnight" (real time)
ROUTING:
- Use async_get_price_info_for_range() wrapper for automatic routing
- Wrapper intelligently splits requests spanning the boundary:
* Fully historical range (end < boundary) PRICE_INFO_RANGE only
* Fully recent range (start >= boundary) PRICE_INFO only
* Spanning range Both queries, merged results
- Boundary calculated using REAL TIME (dt_utils.now()), not TimeService
to ensure predictable API responses
USER:
- Fetches user account data and home metadata
- Separate from price data queries
"""
class QueryType(Enum):
"""Types of queries that can be made to the API."""
PRICE_INFO = "price_info"
PRICE_INFO_RANGE = "price_info_range"
DAILY_RATING = "daily"
HOURLY_RATING = "hourly"
MONTHLY_RATING = "monthly"
USER = "user"

View file

@ -4,19 +4,9 @@ from __future__ import annotations
from typing import TYPE_CHECKING
from custom_components.tibber_prices.const import get_display_unit_factor
from custom_components.tibber_prices.coordinator.helpers import get_intervals_for_day_offsets
from custom_components.tibber_prices.entity_utils import add_icon_color_attribute
# Constants for price display conversion
_SUBUNIT_FACTOR = 100 # Conversion factor for subunit currency (ct/øre)
_SUBUNIT_PRECISION = 2 # Decimal places for subunit currency
_BASE_PRECISION = 4 # Decimal places for base currency
# Import TypedDict definitions for documentation (not used in signatures)
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator.time_service import TibberPricesTimeService
from custom_components.tibber_prices.utils.average import round_to_nearest_quarter_hour
from homeassistant.util import dt as dt_util
if TYPE_CHECKING:
from datetime import datetime
@ -24,20 +14,15 @@ if TYPE_CHECKING:
from custom_components.tibber_prices.data import TibberPricesConfigEntry
from homeassistant.core import HomeAssistant
from .definitions import MIN_TOMORROW_INTERVALS_15MIN
def get_tomorrow_data_available_attributes(
coordinator_data: dict,
*,
time: TibberPricesTimeService,
) -> dict | None:
def get_tomorrow_data_available_attributes(coordinator_data: dict) -> dict | None:
"""
Build attributes for tomorrow_data_available sensor.
Returns TomorrowDataAvailableAttributes structure.
Args:
coordinator_data: Coordinator data dict
time: TibberPricesTimeService instance
Returns:
Attributes dict with intervals_available and data_status
@ -46,17 +31,13 @@ def get_tomorrow_data_available_attributes(
if not coordinator_data:
return None
# Use helper to get tomorrow's intervals
tomorrow_prices = get_intervals_for_day_offsets(coordinator_data, [1])
tomorrow_date = time.get_local_date(offset_days=1)
price_info = coordinator_data.get("priceInfo", {})
tomorrow_prices = price_info.get("tomorrow", [])
interval_count = len(tomorrow_prices)
# Get expected intervals for tomorrow (handles DST)
expected_intervals = time.get_expected_intervals_for_day(tomorrow_date)
if interval_count == 0:
status = "none"
elif interval_count == expected_intervals:
elif interval_count == MIN_TOMORROW_INTERVALS_15MIN:
status = "full"
else:
status = "partial"
@ -70,79 +51,64 @@ def get_tomorrow_data_available_attributes(
def get_price_intervals_attributes(
coordinator_data: dict,
*,
time: TibberPricesTimeService,
reverse_sort: bool,
config_entry: TibberPricesConfigEntry,
) -> dict | None:
"""
Build attributes for period-based sensors (best/peak price).
Returns PeriodAttributes structure.
All data is already calculated in the coordinator - we just need to:
1. Get period summaries from coordinator (already filtered and fully calculated)
2. Add the current timestamp
3. Find current or next period based on time
4. Convert prices to display units based on user configuration
Args:
coordinator_data: Coordinator data dict
time: TibberPricesTimeService instance (required)
reverse_sort: True for peak_price (highest first), False for best_price (lowest first)
config_entry: Config entry for display unit configuration
Returns:
Attributes dict with current/next period and all periods list
"""
if not coordinator_data:
return build_no_periods_result(time=time)
return build_no_periods_result()
# Get precomputed period summaries from coordinator
periods_data = coordinator_data.get("pricePeriods", {})
periods_data = coordinator_data.get("periods", {})
period_type = "peak_price" if reverse_sort else "best_price"
period_data = periods_data.get(period_type)
if not period_data:
return build_no_periods_result(time=time)
return build_no_periods_result()
period_summaries = period_data.get("periods", [])
if not period_summaries:
return build_no_periods_result(time=time)
# Filter periods for today+tomorrow (sensors don't show yesterday's periods)
# Coordinator cache contains yesterday/today/tomorrow, but sensors only need today+tomorrow
now = time.now()
today_start = time.start_of_local_day(now)
filtered_periods = [period for period in period_summaries if period.get("end") and period["end"] >= today_start]
if not filtered_periods:
return build_no_periods_result(time=time)
return build_no_periods_result()
# Find current or next period based on current time
now = dt_util.now()
current_period = None
# First pass: find currently active period
for period in filtered_periods:
for period in period_summaries:
start = period.get("start")
end = period.get("end")
if start and end and time.is_current_interval(start, end):
if start and end and start <= now < end:
current_period = period
break
# Second pass: find next future period if none is active
if not current_period:
for period in filtered_periods:
for period in period_summaries:
start = period.get("start")
if start and time.is_in_future(start):
if start and start > now:
current_period = period
break
# Build final attributes (use filtered_periods for display)
return build_final_attributes_simple(current_period, filtered_periods, time=time, config_entry=config_entry)
# Build final attributes
return build_final_attributes_simple(current_period, period_summaries)
def build_no_periods_result(*, time: TibberPricesTimeService) -> dict:
def build_no_periods_result() -> dict:
"""
Build result when no periods exist (not filtered, just none available).
@ -151,7 +117,7 @@ def build_no_periods_result(*, time: TibberPricesTimeService) -> dict:
"""
# Calculate timestamp: current time rounded down to last quarter hour
now = time.now()
now = dt_util.now()
current_minute = (now.minute // 15) * 15
timestamp = now.replace(minute=current_minute, second=0, microsecond=0)
@ -184,60 +150,26 @@ def add_decision_attributes(attributes: dict, current_period: dict) -> None:
attributes["rating_difference_%"] = current_period["rating_difference_%"]
def add_price_attributes(attributes: dict, current_period: dict, factor: int) -> None:
"""
Add price statistics attributes (priority 3).
Args:
attributes: Target dict to add attributes to
current_period: Period dict with price data (in base currency)
factor: Display unit conversion factor (100 for subunit, 1 for base)
"""
# Convert prices from base currency to display units
precision = _SUBUNIT_PRECISION if factor == _SUBUNIT_FACTOR else _BASE_PRECISION
if "price_mean" in current_period:
attributes["price_mean"] = round(current_period["price_mean"] * factor, precision)
if "price_median" in current_period:
attributes["price_median"] = round(current_period["price_median"] * factor, precision)
def add_price_attributes(attributes: dict, current_period: dict) -> None:
"""Add price statistics attributes (priority 3)."""
if "price_avg" in current_period:
attributes["price_avg"] = current_period["price_avg"]
if "price_min" in current_period:
attributes["price_min"] = round(current_period["price_min"] * factor, precision)
attributes["price_min"] = current_period["price_min"]
if "price_max" in current_period:
attributes["price_max"] = round(current_period["price_max"] * factor, precision)
attributes["price_max"] = current_period["price_max"]
if "price_spread" in current_period:
attributes["price_spread"] = round(current_period["price_spread"] * factor, precision)
if "price_coefficient_variation_%" in current_period:
attributes["price_coefficient_variation_%"] = current_period["price_coefficient_variation_%"]
attributes["price_spread"] = current_period["price_spread"]
if "volatility" in current_period:
attributes["volatility"] = current_period["volatility"] # Volatility is not a price, keep as-is
attributes["volatility"] = current_period["volatility"]
def add_comparison_attributes(attributes: dict, current_period: dict, factor: int) -> None:
"""
Add price comparison attributes (priority 4).
Args:
attributes: Target dict to add attributes to
current_period: Period dict with price diff data (in base currency)
factor: Display unit conversion factor (100 for subunit, 1 for base)
"""
# Convert price differences from base currency to display units
precision = _SUBUNIT_PRECISION if factor == _SUBUNIT_FACTOR else _BASE_PRECISION
def add_comparison_attributes(attributes: dict, current_period: dict) -> None:
"""Add price comparison attributes (priority 4)."""
if "period_price_diff_from_daily_min" in current_period:
attributes["period_price_diff_from_daily_min"] = round(
current_period["period_price_diff_from_daily_min"] * factor, precision
)
attributes["period_price_diff_from_daily_min"] = current_period["period_price_diff_from_daily_min"]
if "period_price_diff_from_daily_min_%" in current_period:
attributes["period_price_diff_from_daily_min_%"] = current_period["period_price_diff_from_daily_min_%"]
if "period_price_diff_from_daily_max" in current_period:
attributes["period_price_diff_from_daily_max"] = round(
current_period["period_price_diff_from_daily_max"] * factor, precision
)
if "period_price_diff_from_daily_max_%" in current_period:
attributes["period_price_diff_from_daily_max_%"] = current_period["period_price_diff_from_daily_max_%"]
def add_detail_attributes(attributes: dict, current_period: dict) -> None:
@ -269,51 +201,9 @@ def add_relaxation_attributes(attributes: dict, current_period: dict) -> None:
attributes["relaxation_threshold_applied_%"] = current_period["relaxation_threshold_applied_%"]
def _convert_periods_to_display_units(period_summaries: list[dict], factor: int) -> list[dict]:
"""
Convert price values in periods array to display units.
Args:
period_summaries: List of period dicts with price data (in base currency)
factor: Display unit conversion factor (100 for subunit, 1 for base)
Returns:
New list with converted period dicts
"""
precision = _SUBUNIT_PRECISION if factor == _SUBUNIT_FACTOR else _BASE_PRECISION
converted_periods = []
for period in period_summaries:
converted = period.copy()
# Convert all price fields
price_fields = ["price_mean", "price_median", "price_min", "price_max", "price_spread"]
for field in price_fields:
if field in converted:
converted[field] = round(converted[field] * factor, precision)
# Convert price differences (not percentages)
if "period_price_diff_from_daily_min" in converted:
converted["period_price_diff_from_daily_min"] = round(
converted["period_price_diff_from_daily_min"] * factor, precision
)
if "period_price_diff_from_daily_max" in converted:
converted["period_price_diff_from_daily_max"] = round(
converted["period_price_diff_from_daily_max"] * factor, precision
)
converted_periods.append(converted)
return converted_periods
def build_final_attributes_simple(
current_period: dict | None,
period_summaries: list[dict],
*,
time: TibberPricesTimeService,
config_entry: TibberPricesConfigEntry,
) -> dict:
"""
Build the final attributes dictionary from coordinator's period summaries.
@ -322,12 +212,11 @@ def build_final_attributes_simple(
1. Adds the current timestamp (only thing calculated every 15min)
2. Uses the current/next period from summaries
3. Adds nested period summaries
4. Converts prices to display units based on user configuration
Attributes are ordered following the documented priority:
1. Time information (timestamp, start, end, duration)
2. Core decision attributes (level, rating_level, rating_difference_%)
3. Price statistics (price_mean, price_median, price_min, price_max, price_spread, volatility)
3. Price statistics (price_avg, price_min, price_max, price_spread, volatility)
4. Price differences (period_price_diff_from_daily_min, period_price_diff_from_daily_min_%)
5. Detail information (period_interval_count, period_position, periods_total, periods_remaining)
6. Relaxation information (relaxation_active, relaxation_level, relaxation_threshold_original_%,
@ -337,20 +226,15 @@ def build_final_attributes_simple(
Args:
current_period: The current or next period (already complete from coordinator)
period_summaries: All period summaries from coordinator
time: TibberPricesTimeService instance (required)
config_entry: Config entry for display unit configuration
Returns:
Complete attributes dict with all fields
"""
now = time.now()
now = dt_util.now()
current_minute = (now.minute // 15) * 15
timestamp = now.replace(minute=current_minute, second=0, microsecond=0)
# Get display unit factor (100 for subunit, 1 for base currency)
factor = get_display_unit_factor(config_entry)
if current_period:
# Build attributes in priority order using helper methods
attributes = {}
@ -361,11 +245,11 @@ def build_final_attributes_simple(
# 2. Core decision attributes
add_decision_attributes(attributes, current_period)
# 3. Price statistics (converted to display units)
add_price_attributes(attributes, current_period, factor)
# 3. Price statistics
add_price_attributes(attributes, current_period)
# 4. Price differences (converted to display units)
add_comparison_attributes(attributes, current_period, factor)
# 4. Price differences
add_comparison_attributes(attributes, current_period)
# 5. Detail information
add_detail_attributes(attributes, current_period)
@ -373,15 +257,15 @@ def build_final_attributes_simple(
# 6. Relaxation information (only if period was relaxed)
add_relaxation_attributes(attributes, current_period)
# 7. Meta information (periods array - prices converted to display units)
attributes["periods"] = _convert_periods_to_display_units(period_summaries, factor)
# 7. Meta information (periods array)
attributes["periods"] = period_summaries
return attributes
# No current/next period found - return all periods with timestamp (prices converted)
# No current/next period found - return all periods with timestamp
return {
"timestamp": timestamp,
"periods": _convert_periods_to_display_units(period_summaries, factor),
"periods": period_summaries,
}
@ -390,7 +274,6 @@ async def build_async_extra_state_attributes( # noqa: PLR0913
translation_key: str | None,
hass: HomeAssistant,
*,
time: TibberPricesTimeService,
config_entry: TibberPricesConfigEntry,
sensor_attrs: dict | None = None,
is_on: bool | None = None,
@ -404,23 +287,22 @@ async def build_async_extra_state_attributes( # noqa: PLR0913
entity_key: Entity key (e.g., "best_price_period")
translation_key: Translation key for entity
hass: Home Assistant instance
time: TibberPricesTimeService instance (required)
config_entry: Config entry with options (keyword-only)
sensor_attrs: Sensor-specific attributes (keyword-only)
is_on: Binary sensor state (keyword-only)
Returns:
Complete attributes dict with descriptions (synchronous)
Complete attributes dict with descriptions
"""
# Calculate default timestamp: current time rounded to nearest quarter hour
# This ensures all binary sensors have a consistent reference time for when calculations were made
# Individual sensors can override this via sensor_attrs if needed
now = time.now()
default_timestamp = time.round_to_nearest_quarter(now)
now = dt_util.now()
default_timestamp = round_to_nearest_quarter_hour(now)
attributes = {
"timestamp": default_timestamp,
"timestamp": default_timestamp.isoformat(),
}
# Add sensor-specific attributes (may override timestamp)
@ -453,7 +335,6 @@ def build_sync_extra_state_attributes( # noqa: PLR0913
translation_key: str | None,
hass: HomeAssistant,
*,
time: TibberPricesTimeService,
config_entry: TibberPricesConfigEntry,
sensor_attrs: dict | None = None,
is_on: bool | None = None,
@ -467,7 +348,6 @@ def build_sync_extra_state_attributes( # noqa: PLR0913
entity_key: Entity key (e.g., "best_price_period")
translation_key: Translation key for entity
hass: Home Assistant instance
time: TibberPricesTimeService instance (required)
config_entry: Config entry with options (keyword-only)
sensor_attrs: Sensor-specific attributes (keyword-only)
is_on: Binary sensor state (keyword-only)
@ -479,11 +359,11 @@ def build_sync_extra_state_attributes( # noqa: PLR0913
# Calculate default timestamp: current time rounded to nearest quarter hour
# This ensures all binary sensors have a consistent reference time for when calculations were made
# Individual sensors can override this via sensor_attrs if needed
now = time.now()
default_timestamp = time.round_to_nearest_quarter(now)
now = dt_util.now()
default_timestamp = round_to_nearest_quarter_hour(now)
attributes = {
"timestamp": default_timestamp,
"timestamp": default_timestamp.isoformat(),
}
# Add sensor-specific attributes (may override timestamp)

View file

@ -2,11 +2,10 @@
from __future__ import annotations
from datetime import timedelta
from typing import TYPE_CHECKING
from custom_components.tibber_prices.coordinator import TIME_SENSITIVE_ENTITY_KEYS
from custom_components.tibber_prices.coordinator.core import get_connection_state
from custom_components.tibber_prices.coordinator.helpers import get_intervals_for_day_offsets
from custom_components.tibber_prices.entity import TibberPricesEntity
from custom_components.tibber_prices.entity_utils import get_binary_sensor_icon
from homeassistant.components.binary_sensor import (
@ -14,8 +13,7 @@ from homeassistant.components.binary_sensor import (
BinarySensorEntityDescription,
)
from homeassistant.core import callback
from homeassistant.exceptions import ConfigEntryAuthFailed
from homeassistant.helpers.restore_state import RestoreEntity
from homeassistant.util import dt as dt_util
from .attributes import (
build_async_extra_state_attributes,
@ -23,6 +21,10 @@ from .attributes import (
get_price_intervals_attributes,
get_tomorrow_data_available_attributes,
)
from .definitions import (
MIN_TOMORROW_INTERVALS_15MIN,
PERIOD_LOOKAHEAD_HOURS,
)
if TYPE_CHECKING:
from collections.abc import Callable
@ -30,44 +32,10 @@ if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator import (
TibberPricesDataUpdateCoordinator,
)
from custom_components.tibber_prices.coordinator.time_service import TibberPricesTimeService
class TibberPricesBinarySensor(TibberPricesEntity, BinarySensorEntity, RestoreEntity):
"""tibber_prices binary_sensor class with state restoration."""
# Attributes excluded from recorder history
# See: https://developers.home-assistant.io/docs/core/entity/#excluding-state-attributes-from-recorder-history
_unrecorded_attributes = frozenset(
{
"timestamp",
# Descriptions/Help Text (static, large)
"description",
"usage_tips",
# Large Nested Structures
"periods", # Array of all period summaries
# Frequently Changing Diagnostics
"icon_color",
"data_status",
# Static/Rarely Changing
"level_value",
"rating_value",
"level_id",
"rating_id",
# Relaxation Details
"relaxation_level",
"relaxation_threshold_original_%",
"relaxation_threshold_applied_%",
# Redundant/Derived
"price_spread",
"volatility",
"rating_difference_%",
"period_price_diff_from_daily_min",
"period_price_diff_from_daily_min_%",
"periods_total",
"periods_remaining",
}
)
class TibberPricesBinarySensor(TibberPricesEntity, BinarySensorEntity):
"""tibber_prices binary_sensor class."""
def __init__(
self,
@ -85,11 +53,6 @@ class TibberPricesBinarySensor(TibberPricesEntity, BinarySensorEntity, RestoreEn
"""When entity is added to hass."""
await super().async_added_to_hass()
# Restore last state if available
if (last_state := await self.async_get_last_state()) is not None and last_state.state in ("on", "off"):
# Restore binary state (on/off) - will be used until first coordinator update
self._attr_is_on = last_state.state == "on"
# Register with coordinator for time-sensitive updates if applicable
if self.entity_description.key in TIME_SENSITIVE_ENTITY_KEYS:
self._time_sensitive_remove_listener = self.coordinator.async_add_time_sensitive_listener(
@ -106,17 +69,8 @@ class TibberPricesBinarySensor(TibberPricesEntity, BinarySensorEntity, RestoreEn
self._time_sensitive_remove_listener = None
@callback
def _handle_time_sensitive_update(self, time_service: TibberPricesTimeService) -> None:
"""
Handle time-sensitive update from coordinator.
Args:
time_service: TibberPricesTimeService instance with reference time for this update cycle
"""
# Store TimeService from Timer #2 for calculations during this update cycle
self.coordinator.time = time_service
def _handle_time_sensitive_update(self) -> None:
"""Handle time-sensitive update from coordinator."""
self.async_write_ha_state()
def _get_value_getter(self) -> Callable | None:
@ -126,7 +80,7 @@ class TibberPricesBinarySensor(TibberPricesEntity, BinarySensorEntity, RestoreEn
state_getters = {
"peak_price_period": self._peak_price_state,
"best_price_period": self._best_price_state,
"connection": lambda: get_connection_state(self.coordinator),
"connection": lambda: True if self.coordinator.data else None,
"tomorrow_data_available": self._tomorrow_data_available_state,
"has_ventilation_system": self._has_ventilation_system_state,
"realtime_consumption_enabled": self._realtime_consumption_enabled_state,
@ -138,90 +92,43 @@ class TibberPricesBinarySensor(TibberPricesEntity, BinarySensorEntity, RestoreEn
"""Return True if the current time is within a best price period."""
if not self.coordinator.data:
return None
attrs = get_price_intervals_attributes(
self.coordinator.data,
reverse_sort=False,
time=self.coordinator.time,
config_entry=self.coordinator.config_entry,
)
attrs = get_price_intervals_attributes(self.coordinator.data, reverse_sort=False)
if not attrs:
return False # Should not happen, but safety fallback
start = attrs.get("start")
end = attrs.get("end")
if not start or not end:
return False # No period found = sensor is off
time = self.coordinator.time
return time.is_time_in_period(start, end)
now = dt_util.now()
return start <= now < end
def _peak_price_state(self) -> bool | None:
"""Return True if the current time is within a peak price period."""
if not self.coordinator.data:
return None
attrs = get_price_intervals_attributes(
self.coordinator.data,
reverse_sort=True,
time=self.coordinator.time,
config_entry=self.coordinator.config_entry,
)
attrs = get_price_intervals_attributes(self.coordinator.data, reverse_sort=True)
if not attrs:
return False # Should not happen, but safety fallback
start = attrs.get("start")
end = attrs.get("end")
if not start or not end:
return False # No period found = sensor is off
time = self.coordinator.time
return time.is_time_in_period(start, end)
now = dt_util.now()
return start <= now < end
def _tomorrow_data_available_state(self) -> bool | None:
"""Return True if tomorrow's data is fully available, False if not, None if unknown."""
# Auth errors: Cannot reliably check - return unknown
# User must fix auth via reauth flow before we can determine tomorrow data availability
if isinstance(self.coordinator.last_exception, ConfigEntryAuthFailed):
return None
# No data: unknown state (initializing or error)
if not self.coordinator.data:
return None
# Check tomorrow data availability (normal operation)
tomorrow_prices = get_intervals_for_day_offsets(self.coordinator.data, [1])
tomorrow_date = self.coordinator.time.get_local_date(offset_days=1)
price_info = self.coordinator.data.get("priceInfo", {})
tomorrow_prices = price_info.get("tomorrow", [])
interval_count = len(tomorrow_prices)
# Get expected intervals for tomorrow (handles DST)
expected_intervals = self.coordinator.time.get_expected_intervals_for_day(tomorrow_date)
if interval_count == expected_intervals:
if interval_count == MIN_TOMORROW_INTERVALS_15MIN:
return True
if interval_count == 0:
return False
return False
@property
def available(self) -> bool:
"""
Return if entity is available.
Override base implementation for connection sensor which should
always be available to show connection state.
"""
# Connection sensor is always available (shows connection state)
if self.entity_description.key == "connection":
return True
# All other binary sensors use base availability logic
return super().available
@property
def force_update(self) -> bool:
"""
Force update for connection sensor to record all state changes.
Connection sensor should write every state change to history,
even if the state (on/off) is the same, to track connectivity issues.
"""
return self.entity_description.key == "connection"
def _has_ventilation_system_state(self) -> bool | None:
"""Return True if the home has a ventilation system."""
if not self.coordinator.data:
@ -268,7 +175,7 @@ class TibberPricesBinarySensor(TibberPricesEntity, BinarySensorEntity, RestoreEn
def _get_tomorrow_data_available_attributes(self) -> dict | None:
"""Return attributes for tomorrow_data_available binary sensor."""
return get_tomorrow_data_available_attributes(self.coordinator.data, time=self.coordinator.time)
return get_tomorrow_data_available_attributes(self.coordinator.data)
def _get_sensor_attributes(self) -> dict | None:
"""
@ -280,19 +187,9 @@ class TibberPricesBinarySensor(TibberPricesEntity, BinarySensorEntity, RestoreEn
key = self.entity_description.key
if key == "peak_price_period":
return get_price_intervals_attributes(
self.coordinator.data,
reverse_sort=True,
time=self.coordinator.time,
config_entry=self.coordinator.config_entry,
)
return get_price_intervals_attributes(self.coordinator.data, reverse_sort=True)
if key == "best_price_period":
return get_price_intervals_attributes(
self.coordinator.data,
reverse_sort=False,
time=self.coordinator.time,
config_entry=self.coordinator.config_entry,
)
return get_price_intervals_attributes(self.coordinator.data, reverse_sort=False)
if key == "tomorrow_data_available":
return self._get_tomorrow_data_available_attributes()
@ -301,13 +198,11 @@ class TibberPricesBinarySensor(TibberPricesEntity, BinarySensorEntity, RestoreEn
@callback
def _handle_coordinator_update(self) -> None:
"""Handle updated data from the coordinator."""
# All binary sensors get push updates when coordinator has new data:
# - tomorrow_data_available: Reflects new data availability immediately after API fetch
# - connection: Reflects connection state changes immediately
# - chart_data_export: Updates chart data when price data changes
# - peak_price_period, best_price_period: Update when periods change (also get Timer #2 updates)
# - data_lifecycle_status: Gets both push and Timer #2 updates
self.async_write_ha_state()
# Chart data export: No automatic refresh needed.
# Data only refreshes on:
# 1. Initial sensor activation (async_added_to_hass)
# 2. Config changes via Options Flow (triggers re-add)
# Hourly coordinator updates don't change the chart data content.
@property
def is_on(self) -> bool | None:
@ -345,28 +240,31 @@ class TibberPricesBinarySensor(TibberPricesEntity, BinarySensorEntity, RestoreEn
def _has_future_periods(self) -> bool:
"""
Check if there are any future periods.
Check if there are periods starting within the next 6 hours.
Returns True if any period starts in the future (no time limit).
This ensures icons show "waiting" state whenever periods are scheduled.
Returns True if any period starts between now and PERIOD_LOOKAHEAD_HOURS from now.
This provides a practical planning horizon instead of hard midnight cutoff.
"""
attrs = self._get_sensor_attributes()
if not attrs or "periods" not in attrs:
return False
time = self.coordinator.time
now = dt_util.now()
horizon = now + timedelta(hours=PERIOD_LOOKAHEAD_HOURS)
periods = attrs.get("periods", [])
# Check if any period starts in the future (no time limit)
# Check if any period starts within the look-ahead window
for period in periods:
start_str = period.get("start")
if start_str:
# Already datetime object (periods come from coordinator.data)
start_time = start_str if not isinstance(start_str, str) else time.parse_datetime(start_str)
# Parse datetime if it's a string, otherwise use as-is
start_time = dt_util.parse_datetime(start_str) if isinstance(start_str, str) else start_str
# Period starts in the future
if start_time and time.is_in_future(start_time):
return True
if start_time:
start_time_local = dt_util.as_local(start_time)
# Period starts in the future but within our horizon
if now < start_time_local <= horizon:
return True
return False
@ -388,7 +286,6 @@ class TibberPricesBinarySensor(TibberPricesEntity, BinarySensorEntity, RestoreEn
config_entry=self.coordinator.config_entry,
sensor_attrs=sensor_attrs,
is_on=self.is_on,
time=self.coordinator.time,
)
except (KeyError, ValueError, TypeError) as ex:
@ -419,7 +316,6 @@ class TibberPricesBinarySensor(TibberPricesEntity, BinarySensorEntity, RestoreEn
config_entry=self.coordinator.config_entry,
sensor_attrs=sensor_attrs,
is_on=self.is_on,
time=self.coordinator.time,
)
except (KeyError, ValueError, TypeError) as ex:

View file

@ -8,8 +8,12 @@ from homeassistant.components.binary_sensor import (
)
from homeassistant.const import EntityCategory
# Period lookahead removed - icons show "waiting" state if ANY future periods exist
# No artificial time limit - show all periods until midnight
# Constants
MIN_TOMORROW_INTERVALS_15MIN = 96
# Look-ahead window for future period detection (hours)
# Icons will show "waiting" state if a period starts within this window
PERIOD_LOOKAHEAD_HOURS = 6
ENTITY_DESCRIPTIONS = (
BinarySensorEntityDescription(
@ -38,7 +42,6 @@ ENTITY_DESCRIPTIONS = (
icon="mdi:calendar-check",
device_class=None, # No specific device_class = shows generic "On/Off"
entity_category=EntityCategory.DIAGNOSTIC,
entity_registry_enabled_default=True, # Critical for automations
),
BinarySensorEntityDescription(
key="has_ventilation_system",

View file

@ -1,173 +0,0 @@
"""
Type definitions for Tibber Prices binary sensor attributes.
These TypedDict definitions serve as **documentation** of the attribute structure
for each binary sensor type. They enable IDE autocomplete and type checking when
working with attribute dictionaries.
NOTE: In function signatures, we still use dict[str, Any] for flexibility,
but these TypedDict definitions document what keys and types are expected.
IMPORTANT: PriceLevel and PriceRating types are duplicated here to avoid
cross-platform dependencies. Keep in sync with sensor/types.py.
"""
from __future__ import annotations
from typing import Literal, TypedDict
# ============================================================================
# Literal Type Definitions (Duplicated from sensor/types.py)
# ============================================================================
# SYNC: Keep these in sync with:
# 1. sensor/types.py (Literal type definitions)
# 2. const.py (runtime string constants - single source of truth)
#
# const.py defines:
# - PRICE_LEVEL_VERY_CHEAP, PRICE_LEVEL_CHEAP, etc.
# - PRICE_RATING_LOW, PRICE_RATING_NORMAL, etc.
#
# These types are intentionally duplicated here to avoid cross-platform imports.
# Binary sensor attributes need these types for type safety without importing
# from sensor/ package (maintains platform separation).
# Price level literals (shared with sensor platform - keep in sync!)
PriceLevel = Literal[
"VERY_CHEAP",
"CHEAP",
"NORMAL",
"EXPENSIVE",
"VERY_EXPENSIVE",
]
# Price rating literals (shared with sensor platform - keep in sync!)
PriceRating = Literal[
"LOW",
"NORMAL",
"HIGH",
]
class BaseAttributes(TypedDict, total=False):
"""
Base attributes common to all binary sensors.
All binary sensor attributes include at minimum:
- timestamp: ISO 8601 string indicating when the state/attributes are valid
- error: Optional error message if something went wrong
"""
timestamp: str
error: str
class TomorrowDataAvailableAttributes(BaseAttributes, total=False):
"""
Attributes for tomorrow_data_available binary sensor.
Indicates whether tomorrow's price data is available from Tibber API.
"""
intervals_available: int # Number of intervals available for tomorrow
data_status: Literal["none", "partial", "full"] # Data completeness status
class PeriodSummary(TypedDict, total=False):
"""
Structure for period summary nested in period attributes.
Each period summary contains all calculated information about one period.
"""
# Time information (priority 1)
start: str # ISO 8601 timestamp of period start
end: str # ISO 8601 timestamp of period end
duration_minutes: int # Duration in minutes
# Core decision attributes (priority 2)
level: PriceLevel # Price level classification
rating_level: PriceRating # Price rating classification
rating_difference_pct: float # Difference from daily average (%)
# Price statistics (priority 3)
price_mean: float # Arithmetic mean price in period
price_median: float # Median price in period
price_min: float # Minimum price in period
price_max: float # Maximum price in period
price_spread: float # Price spread (max - min)
volatility: float # Price volatility within period
# Price comparison (priority 4)
period_price_diff_from_daily_min: float # Difference from daily min
period_price_diff_from_daily_min_pct: float # Difference from daily min (%)
# Detail information (priority 5)
period_interval_count: int # Number of intervals in period
period_position: int # Period position (1-based)
periods_total: int # Total number of periods
periods_remaining: int # Remaining periods after this one
# Relaxation information (priority 6 - only if period was relaxed)
relaxation_active: bool # Whether this period was found via relaxation
relaxation_level: int # Relaxation level used (1-based)
relaxation_threshold_original_pct: float # Original flex threshold (%)
relaxation_threshold_applied_pct: float # Applied flex threshold after relaxation (%)
class PeriodAttributes(BaseAttributes, total=False):
"""
Attributes for period-based binary sensors (best_price_period, peak_price_period).
These sensors indicate whether the current/next cheap/expensive period is active.
Attributes follow priority ordering:
1. Time information (timestamp, start, end, duration_minutes)
2. Core decision attributes (level, rating_level, rating_difference_%)
3. Price statistics (price_mean, price_median, price_min, price_max, price_spread, volatility)
4. Price comparison (period_price_diff_from_daily_min, period_price_diff_from_daily_min_%)
5. Detail information (period_interval_count, period_position, periods_total, periods_remaining)
6. Relaxation information (only if period was relaxed)
7. Meta information (periods list)
"""
# Time information (priority 1) - start/end refer to current/next period
start: str | None # ISO 8601 timestamp of current/next period start
end: str | None # ISO 8601 timestamp of current/next period end
duration_minutes: int # Duration of current/next period in minutes
# Core decision attributes (priority 2)
level: PriceLevel # Price level of current/next period
rating_level: PriceRating # Price rating of current/next period
rating_difference_pct: float # Difference from daily average (%)
# Price statistics (priority 3)
price_mean: float # Arithmetic mean price in current/next period
price_median: float # Median price in current/next period
price_min: float # Minimum price in current/next period
price_max: float # Maximum price in current/next period
price_spread: float # Price spread (max - min) in current/next period
volatility: float # Price volatility within current/next period
# Price comparison (priority 4)
period_price_diff_from_daily_min: float # Difference from daily min
period_price_diff_from_daily_min_pct: float # Difference from daily min (%)
# Detail information (priority 5)
period_interval_count: int # Number of intervals in current/next period
period_position: int # Period position (1-based)
periods_total: int # Total number of periods found
periods_remaining: int # Remaining periods after current/next one
# Relaxation information (priority 6 - only if period was relaxed)
relaxation_active: bool # Whether current/next period was found via relaxation
relaxation_level: int # Relaxation level used (1-based)
relaxation_threshold_original_pct: float # Original flex threshold (%)
relaxation_threshold_applied_pct: float # Applied flex threshold after relaxation (%)
# Meta information (priority 7)
periods: list[PeriodSummary] # All periods found (sorted by start time)
# Union type for all binary sensor attributes (for documentation purposes)
# In actual code, use dict[str, Any] for flexibility
BinarySensorAttributes = TomorrowDataAvailableAttributes | PeriodAttributes

View file

@ -14,7 +14,6 @@ from .config_flow_handlers.schemas import (
get_best_price_schema,
get_options_init_schema,
get_peak_price_schema,
get_price_level_schema,
get_price_rating_schema,
get_price_trend_schema,
get_reauth_confirm_schema,
@ -26,23 +25,22 @@ from .config_flow_handlers.schemas import (
from .config_flow_handlers.subentry_flow import (
TibberPricesSubentryFlowHandler as SubentryFlowHandler,
)
from .config_flow_handlers.user_flow import TibberPricesConfigFlowHandler as ConfigFlow
from .config_flow_handlers.user_flow import TibberPricesFlowHandler as ConfigFlow
from .config_flow_handlers.validators import (
TibberPricesCannotConnectError,
TibberPricesInvalidAuthError,
CannotConnectError,
InvalidAuthError,
validate_api_token,
)
__all__ = [
"CannotConnectError",
"ConfigFlow",
"InvalidAuthError",
"OptionsFlowHandler",
"SubentryFlowHandler",
"TibberPricesCannotConnectError",
"TibberPricesInvalidAuthError",
"get_best_price_schema",
"get_options_init_schema",
"get_peak_price_schema",
"get_price_level_schema",
"get_price_rating_schema",
"get_price_trend_schema",
"get_reauth_confirm_schema",

View file

@ -27,7 +27,6 @@ from custom_components.tibber_prices.config_flow_handlers.schemas import (
get_best_price_schema,
get_options_init_schema,
get_peak_price_schema,
get_price_level_schema,
get_price_rating_schema,
get_price_trend_schema,
get_reauth_confirm_schema,
@ -40,24 +39,23 @@ from custom_components.tibber_prices.config_flow_handlers.subentry_flow import (
TibberPricesSubentryFlowHandler,
)
from custom_components.tibber_prices.config_flow_handlers.user_flow import (
TibberPricesConfigFlowHandler,
TibberPricesFlowHandler,
)
from custom_components.tibber_prices.config_flow_handlers.validators import (
TibberPricesCannotConnectError,
TibberPricesInvalidAuthError,
CannotConnectError,
InvalidAuthError,
validate_api_token,
)
__all__ = [
"TibberPricesCannotConnectError",
"TibberPricesConfigFlowHandler",
"TibberPricesInvalidAuthError",
"CannotConnectError",
"InvalidAuthError",
"TibberPricesFlowHandler",
"TibberPricesOptionsFlowHandler",
"TibberPricesSubentryFlowHandler",
"get_best_price_schema",
"get_options_init_schema",
"get_peak_price_schema",
"get_price_level_schema",
"get_price_rating_schema",
"get_price_trend_schema",
"get_reauth_confirm_schema",

View file

@ -1,243 +0,0 @@
"""
Entity check utilities for options flow.
This module provides functions to check if relevant entities are enabled
for specific options flow steps. If no relevant entities are enabled,
a warning can be displayed to users.
"""
from __future__ import annotations
import logging
from typing import TYPE_CHECKING
from custom_components.tibber_prices.const import DOMAIN
from homeassistant.helpers.entity_registry import async_get as async_get_entity_registry
if TYPE_CHECKING:
from homeassistant.config_entries import ConfigEntry
from homeassistant.core import HomeAssistant
_LOGGER = logging.getLogger(__name__)
# Maximum number of example sensors to show in warning message
MAX_EXAMPLE_SENSORS = 3
# Threshold for using "and" vs "," in formatted names
NAMES_SIMPLE_JOIN_THRESHOLD = 2
# Mapping of options flow steps to affected sensor keys
# These are the entity keys (from sensor/definitions.py and binary_sensor/definitions.py)
# that are affected by each settings page
STEP_TO_SENSOR_KEYS: dict[str, list[str]] = {
# Price Rating settings affect all rating sensors
"current_interval_price_rating": [
# Interval rating sensors
"current_interval_price_rating",
"next_interval_price_rating",
"previous_interval_price_rating",
# Rolling hour rating sensors
"current_hour_price_rating",
"next_hour_price_rating",
# Daily rating sensors
"yesterday_price_rating",
"today_price_rating",
"tomorrow_price_rating",
],
# Price Level settings affect level sensors and period binary sensors
"price_level": [
# Interval level sensors
"current_interval_price_level",
"next_interval_price_level",
"previous_interval_price_level",
# Rolling hour level sensors
"current_hour_price_level",
"next_hour_price_level",
# Daily level sensors
"yesterday_price_level",
"today_price_level",
"tomorrow_price_level",
# Binary sensors that use level filtering
"best_price_period",
"peak_price_period",
],
# Volatility settings affect volatility sensors
"volatility": [
"today_volatility",
"tomorrow_volatility",
"next_24h_volatility",
"today_tomorrow_volatility",
# Also affects trend sensors (adaptive thresholds)
"current_price_trend",
"next_price_trend_change",
"price_trend_1h",
"price_trend_2h",
"price_trend_3h",
"price_trend_4h",
"price_trend_5h",
"price_trend_6h",
"price_trend_8h",
"price_trend_12h",
],
# Best Price settings affect best price binary sensor and timing sensors
"best_price": [
# Binary sensor
"best_price_period",
# Timing sensors
"best_price_end_time",
"best_price_period_duration",
"best_price_remaining_minutes",
"best_price_progress",
"best_price_next_start_time",
"best_price_next_in_minutes",
],
# Peak Price settings affect peak price binary sensor and timing sensors
"peak_price": [
# Binary sensor
"peak_price_period",
# Timing sensors
"peak_price_end_time",
"peak_price_period_duration",
"peak_price_remaining_minutes",
"peak_price_progress",
"peak_price_next_start_time",
"peak_price_next_in_minutes",
],
# Price Trend settings affect trend sensors
"price_trend": [
"current_price_trend",
"next_price_trend_change",
"price_trend_1h",
"price_trend_2h",
"price_trend_3h",
"price_trend_4h",
"price_trend_5h",
"price_trend_6h",
"price_trend_8h",
"price_trend_12h",
],
}
def check_relevant_entities_enabled(
hass: HomeAssistant,
config_entry: ConfigEntry,
step_id: str,
) -> tuple[bool, list[str]]:
"""
Check if any relevant entities for a settings step are enabled.
Args:
hass: Home Assistant instance
config_entry: Current config entry
step_id: The options flow step ID
Returns:
Tuple of (has_enabled_entities, list_of_example_sensor_names)
- has_enabled_entities: True if at least one relevant entity is enabled
- list_of_example_sensor_names: List of example sensor keys for the warning message
"""
sensor_keys = STEP_TO_SENSOR_KEYS.get(step_id)
if not sensor_keys:
# No mapping for this step - no check needed
return True, []
entity_registry = async_get_entity_registry(hass)
entry_id = config_entry.entry_id
enabled_count = 0
example_sensors: list[str] = []
for entity in entity_registry.entities.values():
# Check if entity belongs to our integration and config entry
if entity.config_entry_id != entry_id:
continue
if entity.platform != DOMAIN:
continue
# Extract the sensor key from unique_id
# unique_id format: "{home_id}_{sensor_key}" or "{entry_id}_{sensor_key}"
unique_id = entity.unique_id or ""
# The sensor key is after the last underscore that separates the ID prefix
# We check if any of our target keys is contained in the unique_id
for sensor_key in sensor_keys:
if unique_id.endswith(f"_{sensor_key}") or unique_id == sensor_key:
# Found a matching entity
if entity.disabled_by is None:
# Entity is enabled
enabled_count += 1
break
# Entity is disabled - add to examples (max MAX_EXAMPLE_SENSORS)
if len(example_sensors) < MAX_EXAMPLE_SENSORS and sensor_key not in example_sensors:
example_sensors.append(sensor_key)
break
# If we found enabled entities, return success
if enabled_count > 0:
return True, []
# No enabled entities - return the example sensors for the warning
# If we haven't collected any examples yet, use the first from the mapping
if not example_sensors:
example_sensors = sensor_keys[:MAX_EXAMPLE_SENSORS]
return False, example_sensors
def format_sensor_names_for_warning(sensor_keys: list[str]) -> str:
"""
Format sensor keys into human-readable names for warning message.
Args:
sensor_keys: List of sensor keys
Returns:
Formatted string like "Best Price Period, Best Price End Time, ..."
"""
# Convert snake_case keys to Title Case names
names = []
for key in sensor_keys:
# Replace underscores with spaces and title case
name = key.replace("_", " ").title()
names.append(name)
if len(names) <= NAMES_SIMPLE_JOIN_THRESHOLD:
return " and ".join(names)
return ", ".join(names[:-1]) + ", and " + names[-1]
def check_chart_data_export_enabled(
hass: HomeAssistant,
config_entry: ConfigEntry,
) -> bool:
"""
Check if the Chart Data Export sensor is enabled.
Args:
hass: Home Assistant instance
config_entry: Current config entry
Returns:
True if the Chart Data Export sensor is enabled, False otherwise
"""
entity_registry = async_get_entity_registry(hass)
entry_id = config_entry.entry_id
for entity in entity_registry.entities.values():
# Check if entity belongs to our integration and config entry
if entity.config_entry_id != entry_id:
continue
if entity.platform != DOMAIN:
continue
# Check for chart_data_export sensor
unique_id = entity.unique_id or ""
if unique_id.endswith("_chart_data_export") or unique_id == "chart_data_export":
# Found the entity - check if enabled
return entity.disabled_by is None
# Entity not found (shouldn't happen, but treat as disabled)
return False

View file

@ -3,81 +3,21 @@
from __future__ import annotations
import logging
from copy import deepcopy
from typing import TYPE_CHECKING, Any
from typing import Any, ClassVar
if TYPE_CHECKING:
from collections.abc import Mapping
import yaml
from custom_components.tibber_prices.config_flow_handlers.entity_check import (
check_chart_data_export_enabled,
check_relevant_entities_enabled,
format_sensor_names_for_warning,
)
from custom_components.tibber_prices.config_flow_handlers.schemas import (
ConfigOverrides,
get_best_price_schema,
get_chart_data_export_schema,
get_display_settings_schema,
get_options_init_schema,
get_peak_price_schema,
get_price_level_schema,
get_price_rating_schema,
get_price_trend_schema,
get_reset_to_defaults_schema,
get_volatility_schema,
)
from custom_components.tibber_prices.config_flow_handlers.validators import (
validate_best_price_distance_percentage,
validate_distance_percentage,
validate_flex_percentage,
validate_gap_count,
validate_min_periods,
validate_period_length,
validate_price_rating_threshold_high,
validate_price_rating_threshold_low,
validate_price_rating_thresholds,
validate_price_trend_falling,
validate_price_trend_rising,
validate_price_trend_strongly_falling,
validate_price_trend_strongly_rising,
validate_relaxation_attempts,
validate_volatility_threshold_high,
validate_volatility_threshold_moderate,
validate_volatility_threshold_very_high,
validate_volatility_thresholds,
)
from custom_components.tibber_prices.const import (
CONF_BEST_PRICE_FLEX,
CONF_BEST_PRICE_MAX_LEVEL_GAP_COUNT,
CONF_BEST_PRICE_MIN_DISTANCE_FROM_AVG,
CONF_BEST_PRICE_MIN_PERIOD_LENGTH,
CONF_MIN_PERIODS_BEST,
CONF_MIN_PERIODS_PEAK,
CONF_PEAK_PRICE_FLEX,
CONF_PEAK_PRICE_MAX_LEVEL_GAP_COUNT,
CONF_PEAK_PRICE_MIN_DISTANCE_FROM_AVG,
CONF_PEAK_PRICE_MIN_PERIOD_LENGTH,
CONF_PRICE_RATING_THRESHOLD_HIGH,
CONF_PRICE_RATING_THRESHOLD_LOW,
CONF_PRICE_TREND_THRESHOLD_FALLING,
CONF_PRICE_TREND_THRESHOLD_RISING,
CONF_PRICE_TREND_THRESHOLD_STRONGLY_FALLING,
CONF_PRICE_TREND_THRESHOLD_STRONGLY_RISING,
CONF_RELAXATION_ATTEMPTS_BEST,
CONF_RELAXATION_ATTEMPTS_PEAK,
CONF_VOLATILITY_THRESHOLD_HIGH,
CONF_VOLATILITY_THRESHOLD_MODERATE,
CONF_VOLATILITY_THRESHOLD_VERY_HIGH,
DEFAULT_VOLATILITY_THRESHOLD_HIGH,
DEFAULT_VOLATILITY_THRESHOLD_MODERATE,
DEFAULT_VOLATILITY_THRESHOLD_VERY_HIGH,
DOMAIN,
async_get_translation,
get_default_options,
)
from custom_components.tibber_prices.const import DOMAIN
from homeassistant.config_entries import ConfigFlowResult, OptionsFlow
from homeassistant.helpers import entity_registry as er
_LOGGER = logging.getLogger(__name__)
@ -85,811 +25,173 @@ _LOGGER = logging.getLogger(__name__)
class TibberPricesOptionsFlowHandler(OptionsFlow):
"""Handle options for tibber_prices entries."""
# Step progress tracking
_TOTAL_STEPS: ClassVar[int] = 7
_STEP_INFO: ClassVar[dict[str, int]] = {
"init": 1,
"current_interval_price_rating": 2,
"volatility": 3,
"best_price": 4,
"peak_price": 5,
"price_trend": 6,
"chart_data_export": 7,
}
def __init__(self) -> None:
"""Initialize options flow."""
self._options: dict[str, Any] = {}
def _merge_section_data(self, user_input: dict[str, Any]) -> None:
"""
Merge section data from form input into options.
Home Assistant forms with section() return nested dicts like:
{"section_name": {"setting1": value1, "setting2": value2}}
We need to preserve this structure in config_entry.options.
Args:
user_input: Nested user input from form with sections
"""
for section_key, section_data in user_input.items():
if isinstance(section_data, dict):
# This is a section - ensure the section exists in options
if section_key not in self._options:
self._options[section_key] = {}
# Update the section with new values
self._options[section_key].update(section_data)
else:
# This is a direct value - keep it as is
self._options[section_key] = section_data
def _migrate_config_options(self, options: Mapping[str, Any]) -> dict[str, Any]:
"""
Migrate deprecated config options to current format.
This removes obsolete keys and renames changed keys to maintain
compatibility with older config entries.
Args:
options: Original options dict from config_entry
Returns:
Migrated options dict with deprecated keys removed/renamed
"""
# CRITICAL: Use deepcopy to avoid modifying the original config_entry.options
# If we use dict(options), nested dicts are still referenced, causing
# self._options modifications to leak into config_entry.options
migrated = deepcopy(dict(options))
migration_performed = False
# Migration 1: Rename relaxation_step_* to relaxation_attempts_*
# (Changed in v0.6.0 - commit 5a5c8ca)
if "relaxation_step_best" in migrated:
migrated["relaxation_attempts_best"] = migrated.pop("relaxation_step_best")
migration_performed = True
_LOGGER.info(
"Migrated config option: relaxation_step_best -> relaxation_attempts_best (value: %s)",
migrated["relaxation_attempts_best"],
)
if "relaxation_step_peak" in migrated:
migrated["relaxation_attempts_peak"] = migrated.pop("relaxation_step_peak")
migration_performed = True
_LOGGER.info(
"Migrated config option: relaxation_step_peak -> relaxation_attempts_peak (value: %s)",
migrated["relaxation_attempts_peak"],
)
# Migration 2: Remove obsolete volatility filter options
# (Removed in v0.9.0 - volatility filter feature removed)
obsolete_keys = [
"best_price_min_volatility",
"peak_price_min_volatility",
"min_volatility_for_periods",
]
for key in obsolete_keys:
if key in migrated:
old_value = migrated.pop(key)
migration_performed = True
_LOGGER.info(
"Removed obsolete config option: %s (was: %s)",
key,
old_value,
)
if migration_performed:
_LOGGER.info("Config migration completed - deprecated options cleaned up")
return migrated
def _save_options_if_changed(self) -> bool:
"""
Save options only if they actually changed.
Returns:
True if options were updated, False if no changes detected
"""
# Compare old and new options
if self.config_entry.options != self._options:
self.hass.config_entries.async_update_entry(
self.config_entry,
options=self._options,
)
return True
return False
def _get_entity_warning_placeholders(self, step_id: str) -> dict[str, str]:
"""
Get description placeholders for entity availability warning.
Checks if any relevant entities for the step are enabled.
If not, adds a warning placeholder to display in the form description.
Args:
step_id: The options flow step ID
Returns:
Dictionary with placeholder keys for the form description
"""
has_enabled, example_sensors = check_relevant_entities_enabled(self.hass, self.config_entry, step_id)
if has_enabled:
# No warning needed - return empty placeholder
return {"entity_warning": ""}
# Build warning message with example sensor names
sensor_names = format_sensor_names_for_warning(example_sensors)
return {
"entity_warning": f"\n\n⚠️ **Note:** No sensors affected by these settings are currently enabled. "
f"To use these settings, first enable relevant sensors like *{sensor_names}* "
f"in **Settings → Devices & Services → Tibber Prices → Entities**."
}
def _get_enabled_config_entities(self) -> set[str]:
"""
Get config keys that have their config entity enabled.
Checks the entity registry for number/switch entities that override
config values. Returns the config_key for each enabled entity.
Returns:
Set of config keys (e.g., "best_price_flex", "enable_min_periods_best")
"""
enabled_keys: set[str] = set()
ent_reg = er.async_get(self.hass)
_LOGGER.debug(
"Checking for enabled config override entities for entry %s",
self.config_entry.entry_id,
)
# Map entity keys to their config keys
# Entity keys are defined in number/definitions.py and switch/definitions.py
override_entities = {
# Number entities (best price)
"number.best_price_flex_override": "best_price_flex",
"number.best_price_min_distance_override": "best_price_min_distance_from_avg",
"number.best_price_min_period_length_override": "best_price_min_period_length",
"number.best_price_min_periods_override": "min_periods_best",
"number.best_price_relaxation_attempts_override": "relaxation_attempts_best",
"number.best_price_gap_count_override": "best_price_max_level_gap_count",
# Number entities (peak price)
"number.peak_price_flex_override": "peak_price_flex",
"number.peak_price_min_distance_override": "peak_price_min_distance_from_avg",
"number.peak_price_min_period_length_override": "peak_price_min_period_length",
"number.peak_price_min_periods_override": "min_periods_peak",
"number.peak_price_relaxation_attempts_override": "relaxation_attempts_peak",
"number.peak_price_gap_count_override": "peak_price_max_level_gap_count",
# Switch entities
"switch.best_price_enable_relaxation_override": "enable_min_periods_best",
"switch.peak_price_enable_relaxation_override": "enable_min_periods_peak",
}
# Check each possible override entity
for entity_id_suffix, config_key in override_entities.items():
# Entity IDs include device name, so we need to search by unique_id pattern
# The unique_id follows pattern: {config_entry_id}_{entity_key}
domain, entity_key = entity_id_suffix.split(".", 1)
# Find entity by iterating through registry
for entity_entry in ent_reg.entities.values():
if (
entity_entry.domain == domain
and entity_entry.config_entry_id == self.config_entry.entry_id
and entity_entry.unique_id
and entity_entry.unique_id.endswith(entity_key)
and not entity_entry.disabled
):
_LOGGER.debug(
"Found enabled config override entity: %s -> config_key=%s",
entity_entry.entity_id,
config_key,
)
enabled_keys.add(config_key)
break
_LOGGER.debug("Enabled config override keys: %s", enabled_keys)
return enabled_keys
def _get_active_overrides(self) -> ConfigOverrides:
"""
Build override dict from enabled config entities.
Returns a dict structure compatible with schema functions.
"""
enabled_keys = self._get_enabled_config_entities()
if not enabled_keys:
_LOGGER.debug("No enabled config override entities found")
def _get_step_description_placeholders(self, step_id: str) -> dict[str, str]:
"""Get description placeholders with step progress."""
if step_id not in self._STEP_INFO:
return {}
# Build structure expected by schema: {section: {key: True}}
# Section doesn't matter for read_only check, we just need the key present
overrides: ConfigOverrides = {"_enabled": {}}
for key in enabled_keys:
overrides["_enabled"][key] = True
step_num = self._STEP_INFO[step_id]
_LOGGER.debug("Active overrides structure: %s", overrides)
return overrides
# Get translations loaded by Home Assistant
standard_translations_key = f"{DOMAIN}_standard_translations_{self.hass.config.language}"
translations = self.hass.data.get(standard_translations_key, {})
def _get_override_warning_placeholder(self, step_id: str, overrides: ConfigOverrides) -> dict[str, str]:
"""
Get description placeholder for config override warning.
# Get step progress text from translations with placeholders
step_progress_template = translations.get("common", {}).get("step_progress", "Step {step_num} of {total_steps}")
step_progress = step_progress_template.format(step_num=step_num, total_steps=self._TOTAL_STEPS)
Args:
step_id: The options flow step ID (e.g., "best_price", "peak_price")
overrides: Active overrides dictionary
Returns:
Dictionary with 'override_warning' placeholder
"""
# Define which config keys belong to each step
step_keys: dict[str, set[str]] = {
"best_price": {
"best_price_flex",
"best_price_min_distance_from_avg",
"best_price_min_period_length",
"min_periods_best",
"relaxation_attempts_best",
"enable_min_periods_best",
},
"peak_price": {
"peak_price_flex",
"peak_price_min_distance_from_avg",
"peak_price_min_period_length",
"min_periods_peak",
"relaxation_attempts_peak",
"enable_min_periods_peak",
},
return {
"step_progress": step_progress,
}
keys_to_check = step_keys.get(step_id, set())
enabled_keys = overrides.get("_enabled", {})
override_count = sum(1 for k in enabled_keys if k in keys_to_check)
async def async_step_init(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult:
"""Manage the options - General Settings."""
# Initialize options from config_entry on first call
if not self._options:
self._options = dict(self.config_entry.options)
if override_count > 0:
field_word = "field is" if override_count == 1 else "fields are"
return {
"override_warning": (
f"\n\n🔒 **{override_count} {field_word} managed by configuration entities** "
"(grayed out). Disable the config entity to edit here, "
"or change the value directly via the entity."
)
}
return {"override_warning": ""}
async def _get_override_translations(self) -> dict[str, Any]:
"""
Load override translations from common section.
Uses the system language setting from Home Assistant.
Note: HA Options Flow does not provide user_id in context,
so we cannot determine the individual user's language preference.
Returns:
Dictionary with override_warning_template, override_warning_and,
and override_field_label_* keys for each config field.
"""
# Use system language - HA Options Flow context doesn't include user_id
language = self.hass.config.language or "en"
_LOGGER.debug("Loading override translations for language: %s", language)
translations: dict[str, Any] = {}
# Load template and connector from common section
template = await async_get_translation(self.hass, ["common", "override_warning_template"], language)
_LOGGER.debug("Loaded template: %s", template)
if template:
translations["override_warning_template"] = template
and_connector = await async_get_translation(self.hass, ["common", "override_warning_and"], language)
if and_connector:
translations["override_warning_and"] = and_connector
# Load flat field label translations
field_keys = [
"best_price_min_period_length",
"best_price_max_level_gap_count",
"best_price_flex",
"best_price_min_distance_from_avg",
"enable_min_periods_best",
"min_periods_best",
"relaxation_attempts_best",
"peak_price_min_period_length",
"peak_price_max_level_gap_count",
"peak_price_flex",
"peak_price_min_distance_from_avg",
"enable_min_periods_peak",
"min_periods_peak",
"relaxation_attempts_peak",
]
for field_key in field_keys:
translation_key = f"override_field_label_{field_key}"
label = await async_get_translation(self.hass, ["common", translation_key], language)
if label:
translations[translation_key] = label
return translations
async def async_step_init(self, _user_input: dict[str, Any] | None = None) -> ConfigFlowResult:
"""Manage the options - show menu."""
# Always reload options from config_entry to get latest saved state
# This ensures changes from previous steps are visible
self._options = self._migrate_config_options(self.config_entry.options)
# Show menu with all configuration categories
return self.async_show_menu(
step_id="init",
menu_options=[
"general_settings",
"display_settings",
"current_interval_price_rating",
"price_level",
"volatility",
"best_price",
"peak_price",
"price_trend",
"chart_data_export",
"reset_to_defaults",
"finish",
],
)
async def async_step_reset_to_defaults(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult:
"""Reset all settings to factory defaults."""
if user_input is not None:
# Check if user confirmed the reset
if user_input.get("confirm_reset", False):
# Get currency from config_entry.data (this is immutable and safe)
currency_code = self.config_entry.data.get("currency", None)
# Completely replace options with fresh defaults (factory reset)
# This discards ALL old data including legacy structures
self._options = get_default_options(currency_code)
# Force save the new options
self._save_options_if_changed()
_LOGGER.info(
"Factory reset performed for config entry '%s' - all settings restored to defaults",
self.config_entry.title,
)
# Show success message and return to menu
return self.async_abort(reason="reset_successful")
# User didn't check the box - they want to cancel
# Show info message (not error) and return to menu
return self.async_abort(reason="reset_cancelled")
# Show confirmation form with checkbox
return self.async_show_form(
step_id="reset_to_defaults",
data_schema=get_reset_to_defaults_schema(),
)
async def async_step_finish(self, _user_input: dict[str, Any] | None = None) -> ConfigFlowResult:
"""Close the options flow."""
# Use empty reason to close without any message
return self.async_abort(reason="finished")
async def async_step_general_settings(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult:
"""Configure general settings."""
if user_input is not None:
# Update options with new values
self._options.update(user_input)
# Save options only if changed (triggers listeners automatically)
self._save_options_if_changed()
# Return to menu for more changes
return await self.async_step_init()
return await self.async_step_current_interval_price_rating()
return self.async_show_form(
step_id="general_settings",
step_id="init",
data_schema=get_options_init_schema(self.config_entry.options),
description_placeholders={
**self._get_step_description_placeholders("init"),
"user_login": self.config_entry.data.get("user_login", "N/A"),
},
)
async def async_step_display_settings(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult:
"""Configure currency display settings."""
# Get currency from coordinator data (if available)
# During options flow setup, integration might not be fully loaded yet
currency_code = None
if DOMAIN in self.hass.data and self.config_entry.entry_id in self.hass.data[DOMAIN]:
tibber_data = self.hass.data[DOMAIN][self.config_entry.entry_id]
if tibber_data.coordinator.data:
currency_code = tibber_data.coordinator.data.get("currency")
if user_input is not None:
# Update options with new values
self._options.update(user_input)
# async_create_entry automatically handles change detection and listener triggering
self._save_options_if_changed()
# Return to menu for more changes
return await self.async_step_init()
return self.async_show_form(
step_id="display_settings",
data_schema=get_display_settings_schema(self.config_entry.options, currency_code),
)
async def async_step_current_interval_price_rating(
self, user_input: dict[str, Any] | None = None
) -> ConfigFlowResult:
"""Configure price rating thresholds."""
errors: dict[str, str] = {}
if user_input is not None:
# Schema is now flattened - fields come directly in user_input
# But we still need to store them in nested structure for coordinator
# Validate low price rating threshold
if CONF_PRICE_RATING_THRESHOLD_LOW in user_input and not validate_price_rating_threshold_low(
user_input[CONF_PRICE_RATING_THRESHOLD_LOW]
):
errors[CONF_PRICE_RATING_THRESHOLD_LOW] = "invalid_price_rating_low"
# Validate high price rating threshold
if CONF_PRICE_RATING_THRESHOLD_HIGH in user_input and not validate_price_rating_threshold_high(
user_input[CONF_PRICE_RATING_THRESHOLD_HIGH]
):
errors[CONF_PRICE_RATING_THRESHOLD_HIGH] = "invalid_price_rating_high"
# Cross-validate both thresholds together (LOW must be < HIGH)
if not errors:
# Get current values directly from options (now flat)
low_val = user_input.get(
CONF_PRICE_RATING_THRESHOLD_LOW, self._options.get(CONF_PRICE_RATING_THRESHOLD_LOW, -10)
)
high_val = user_input.get(
CONF_PRICE_RATING_THRESHOLD_HIGH, self._options.get(CONF_PRICE_RATING_THRESHOLD_HIGH, 10)
)
if not validate_price_rating_thresholds(low_val, high_val):
# This should never happen given the range constraints, but add error for safety
errors["base"] = "invalid_price_rating_thresholds"
if not errors:
# Store flat data directly in options (no section wrapping)
self._options.update(user_input)
# async_create_entry automatically handles change detection and listener triggering
self._save_options_if_changed()
# Return to menu for more changes
return await self.async_step_init()
self._options.update(user_input)
return await self.async_step_volatility()
return self.async_show_form(
step_id="current_interval_price_rating",
data_schema=get_price_rating_schema(self.config_entry.options),
errors=errors,
description_placeholders=self._get_entity_warning_placeholders("current_interval_price_rating"),
)
async def async_step_price_level(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult:
"""Configure Tibber price level gap tolerance (smoothing for API 'level' field)."""
errors: dict[str, str] = {}
if user_input is not None:
# No validation needed - slider constraints ensure valid range
# Store flat data directly in options
self._options.update(user_input)
# async_create_entry automatically handles change detection and listener triggering
self._save_options_if_changed()
# Return to menu for more changes
return await self.async_step_init()
return self.async_show_form(
step_id="price_level",
data_schema=get_price_level_schema(self.config_entry.options),
errors=errors,
description_placeholders=self._get_entity_warning_placeholders("price_level"),
description_placeholders=self._get_step_description_placeholders("current_interval_price_rating"),
)
async def async_step_best_price(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult:
"""Configure best price period settings."""
errors: dict[str, str] = {}
if user_input is not None:
# Extract settings from sections
period_settings = user_input.get("period_settings", {})
flexibility_settings = user_input.get("flexibility_settings", {})
relaxation_settings = user_input.get("relaxation_and_target_periods", {})
# Validate period length
if CONF_BEST_PRICE_MIN_PERIOD_LENGTH in period_settings and not validate_period_length(
period_settings[CONF_BEST_PRICE_MIN_PERIOD_LENGTH]
):
errors[CONF_BEST_PRICE_MIN_PERIOD_LENGTH] = "invalid_period_length"
# Validate flex percentage
if CONF_BEST_PRICE_FLEX in flexibility_settings and not validate_flex_percentage(
flexibility_settings[CONF_BEST_PRICE_FLEX]
):
errors[CONF_BEST_PRICE_FLEX] = "invalid_flex"
# Validate distance from average (Best Price uses negative values)
if (
CONF_BEST_PRICE_MIN_DISTANCE_FROM_AVG in flexibility_settings
and not validate_best_price_distance_percentage(
flexibility_settings[CONF_BEST_PRICE_MIN_DISTANCE_FROM_AVG]
)
):
errors[CONF_BEST_PRICE_MIN_DISTANCE_FROM_AVG] = "invalid_best_price_distance"
# Validate minimum periods count
if CONF_MIN_PERIODS_BEST in relaxation_settings and not validate_min_periods(
relaxation_settings[CONF_MIN_PERIODS_BEST]
):
errors[CONF_MIN_PERIODS_BEST] = "invalid_min_periods"
# Validate gap count
if CONF_BEST_PRICE_MAX_LEVEL_GAP_COUNT in period_settings and not validate_gap_count(
period_settings[CONF_BEST_PRICE_MAX_LEVEL_GAP_COUNT]
):
errors[CONF_BEST_PRICE_MAX_LEVEL_GAP_COUNT] = "invalid_gap_count"
# Validate relaxation attempts
if CONF_RELAXATION_ATTEMPTS_BEST in relaxation_settings and not validate_relaxation_attempts(
relaxation_settings[CONF_RELAXATION_ATTEMPTS_BEST]
):
errors[CONF_RELAXATION_ATTEMPTS_BEST] = "invalid_relaxation_attempts"
if not errors:
# Merge section data into options
self._merge_section_data(user_input)
# async_create_entry automatically handles change detection and listener triggering
self._save_options_if_changed()
# Return to menu for more changes
return await self.async_step_init()
overrides = self._get_active_overrides()
placeholders = self._get_entity_warning_placeholders("best_price")
placeholders.update(self._get_override_warning_placeholder("best_price", overrides))
# Load translations for override warnings
override_translations = await self._get_override_translations()
self._options.update(user_input)
return await self.async_step_peak_price()
return self.async_show_form(
step_id="best_price",
data_schema=get_best_price_schema(
self.config_entry.options,
overrides=overrides,
translations=override_translations,
),
errors=errors,
description_placeholders=placeholders,
data_schema=get_best_price_schema(self.config_entry.options),
description_placeholders=self._get_step_description_placeholders("best_price"),
)
async def async_step_peak_price(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult:
"""Configure peak price period settings."""
errors: dict[str, str] = {}
if user_input is not None:
# Extract settings from sections
period_settings = user_input.get("period_settings", {})
flexibility_settings = user_input.get("flexibility_settings", {})
relaxation_settings = user_input.get("relaxation_and_target_periods", {})
# Validate period length
if CONF_PEAK_PRICE_MIN_PERIOD_LENGTH in period_settings and not validate_period_length(
period_settings[CONF_PEAK_PRICE_MIN_PERIOD_LENGTH]
):
errors[CONF_PEAK_PRICE_MIN_PERIOD_LENGTH] = "invalid_period_length"
# Validate flex percentage (peak uses negative values)
if CONF_PEAK_PRICE_FLEX in flexibility_settings and not validate_flex_percentage(
flexibility_settings[CONF_PEAK_PRICE_FLEX]
):
errors[CONF_PEAK_PRICE_FLEX] = "invalid_flex"
# Validate distance from average (Peak Price uses positive values)
if CONF_PEAK_PRICE_MIN_DISTANCE_FROM_AVG in flexibility_settings and not validate_distance_percentage(
flexibility_settings[CONF_PEAK_PRICE_MIN_DISTANCE_FROM_AVG]
):
errors[CONF_PEAK_PRICE_MIN_DISTANCE_FROM_AVG] = "invalid_peak_price_distance"
# Validate minimum periods count
if CONF_MIN_PERIODS_PEAK in relaxation_settings and not validate_min_periods(
relaxation_settings[CONF_MIN_PERIODS_PEAK]
):
errors[CONF_MIN_PERIODS_PEAK] = "invalid_min_periods"
# Validate gap count
if CONF_PEAK_PRICE_MAX_LEVEL_GAP_COUNT in period_settings and not validate_gap_count(
period_settings[CONF_PEAK_PRICE_MAX_LEVEL_GAP_COUNT]
):
errors[CONF_PEAK_PRICE_MAX_LEVEL_GAP_COUNT] = "invalid_gap_count"
# Validate relaxation attempts
if CONF_RELAXATION_ATTEMPTS_PEAK in relaxation_settings and not validate_relaxation_attempts(
relaxation_settings[CONF_RELAXATION_ATTEMPTS_PEAK]
):
errors[CONF_RELAXATION_ATTEMPTS_PEAK] = "invalid_relaxation_attempts"
if not errors:
# Merge section data into options
self._merge_section_data(user_input)
# async_create_entry automatically handles change detection and listener triggering
self._save_options_if_changed()
# Return to menu for more changes
return await self.async_step_init()
overrides = self._get_active_overrides()
placeholders = self._get_entity_warning_placeholders("peak_price")
placeholders.update(self._get_override_warning_placeholder("peak_price", overrides))
# Load translations for override warnings
override_translations = await self._get_override_translations()
self._options.update(user_input)
return await self.async_step_price_trend()
return self.async_show_form(
step_id="peak_price",
data_schema=get_peak_price_schema(
self.config_entry.options,
overrides=overrides,
translations=override_translations,
),
errors=errors,
description_placeholders=placeholders,
data_schema=get_peak_price_schema(self.config_entry.options),
description_placeholders=self._get_step_description_placeholders("peak_price"),
)
async def async_step_price_trend(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult:
"""Configure price trend thresholds."""
errors: dict[str, str] = {}
if user_input is not None:
# Schema is now flattened - fields come directly in user_input
# Store them flat in options (no nested structure)
# Validate rising trend threshold
if CONF_PRICE_TREND_THRESHOLD_RISING in user_input and not validate_price_trend_rising(
user_input[CONF_PRICE_TREND_THRESHOLD_RISING]
):
errors[CONF_PRICE_TREND_THRESHOLD_RISING] = "invalid_price_trend_rising"
# Validate falling trend threshold
if CONF_PRICE_TREND_THRESHOLD_FALLING in user_input and not validate_price_trend_falling(
user_input[CONF_PRICE_TREND_THRESHOLD_FALLING]
):
errors[CONF_PRICE_TREND_THRESHOLD_FALLING] = "invalid_price_trend_falling"
# Validate strongly rising trend threshold
if CONF_PRICE_TREND_THRESHOLD_STRONGLY_RISING in user_input and not validate_price_trend_strongly_rising(
user_input[CONF_PRICE_TREND_THRESHOLD_STRONGLY_RISING]
):
errors[CONF_PRICE_TREND_THRESHOLD_STRONGLY_RISING] = "invalid_price_trend_strongly_rising"
# Validate strongly falling trend threshold
if CONF_PRICE_TREND_THRESHOLD_STRONGLY_FALLING in user_input and not validate_price_trend_strongly_falling(
user_input[CONF_PRICE_TREND_THRESHOLD_STRONGLY_FALLING]
):
errors[CONF_PRICE_TREND_THRESHOLD_STRONGLY_FALLING] = "invalid_price_trend_strongly_falling"
# Cross-validation: Ensure rising < strongly_rising and falling > strongly_falling
if not errors:
rising = user_input.get(CONF_PRICE_TREND_THRESHOLD_RISING)
strongly_rising = user_input.get(CONF_PRICE_TREND_THRESHOLD_STRONGLY_RISING)
falling = user_input.get(CONF_PRICE_TREND_THRESHOLD_FALLING)
strongly_falling = user_input.get(CONF_PRICE_TREND_THRESHOLD_STRONGLY_FALLING)
if rising is not None and strongly_rising is not None and rising >= strongly_rising:
errors[CONF_PRICE_TREND_THRESHOLD_STRONGLY_RISING] = (
"invalid_trend_strongly_rising_less_than_rising"
)
if falling is not None and strongly_falling is not None and falling <= strongly_falling:
errors[CONF_PRICE_TREND_THRESHOLD_STRONGLY_FALLING] = (
"invalid_trend_strongly_falling_greater_than_falling"
)
if not errors:
# Store flat data directly in options (no section wrapping)
self._options.update(user_input)
# async_create_entry automatically handles change detection and listener triggering
self._save_options_if_changed()
# Return to menu for more changes
return await self.async_step_init()
self._options.update(user_input)
return await self.async_step_chart_data_export()
return self.async_show_form(
step_id="price_trend",
data_schema=get_price_trend_schema(self.config_entry.options),
errors=errors,
description_placeholders=self._get_entity_warning_placeholders("price_trend"),
description_placeholders=self._get_step_description_placeholders("price_trend"),
)
async def async_step_chart_data_export(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult:
"""Info page for chart data export sensor."""
"""Configure chart data export sensor."""
errors: dict[str, str] = {}
if user_input is not None:
# No changes to save - just return to menu
return await self.async_step_init()
# Get YAML configuration (default to empty string if not provided)
yaml_config = user_input.get("chart_data_config", "")
# Check if the chart data export sensor is enabled
is_enabled = check_chart_data_export_enabled(self.hass, self.config_entry)
if yaml_config.strip(): # Only validate if not empty
try:
parsed = yaml.safe_load(yaml_config)
if parsed is not None and not isinstance(parsed, dict):
errors["base"] = "invalid_yaml_structure"
except yaml.YAMLError:
errors["base"] = "invalid_yaml_syntax"
# Test service call with parsed parameters
if not errors and parsed:
try:
# Add entry_id to service call data
service_data = {**parsed, "entry_id": self.config_entry.entry_id}
# Call the service to validate parameters
await self.hass.services.async_call(
domain="tibber_prices",
service="get_chartdata",
service_data=service_data,
blocking=True,
return_response=True,
)
except Exception as ex: # noqa: BLE001
# Set error with detailed message directly (no translation key)
error_msg = str(ex)
_LOGGER.warning(
"Service validation failed for chart_data_export: %s",
error_msg,
)
# Use field-level error to show detailed message
errors["chart_data_config"] = error_msg
if not errors:
# Explicitly store chart_data_config (including empty string to allow clearing)
self._options.update(user_input)
# Ensure the key exists even if empty
if "chart_data_config" not in user_input:
self._options["chart_data_config"] = ""
return self.async_create_entry(title="", data=self._options)
# Show info-only form with status-dependent description
return self.async_show_form(
step_id="chart_data_export",
data_schema=get_chart_data_export_schema(self.config_entry.options),
description_placeholders={
"sensor_status_info": self._get_chart_export_status_info(is_enabled=is_enabled),
},
)
def _get_chart_export_status_info(self, *, is_enabled: bool) -> str:
"""Get the status info block for chart data export sensor."""
if is_enabled:
return (
"✅ **Status: Sensor is enabled**\n\n"
"The Chart Data Export sensor is currently active and providing data as attributes.\n\n"
"**Configuration (optional):**\n\n"
"Default settings work out-of-the-box (today+tomorrow, 15-minute intervals, prices only).\n\n"
"For customization, add to **`configuration.yaml`**:\n\n"
"```yaml\n"
"tibber_prices:\n"
" chart_export:\n"
" day:\n"
" - today\n"
" - tomorrow\n"
" include_level: true\n"
" include_rating_level: true\n"
"```\n\n"
"**All parameters:** See `tibber_prices.get_chartdata` service documentation"
)
return (
"❌ **Status: Sensor is disabled**\n\n"
"**Enable the sensor:**\n\n"
"1. Open **Settings → Devices & Services → Tibber Prices**\n"
"2. Select your home → Find **'Chart Data Export'** (Diagnostic section)\n"
"3. **Enable the sensor** (disabled by default)"
description_placeholders=self._get_step_description_placeholders("chart_data_export"),
errors=errors,
)
async def async_step_volatility(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult:
"""Configure volatility thresholds and period filtering."""
errors: dict[str, str] = {}
if user_input is not None:
# Schema is now flattened - fields come directly in user_input
# Validate moderate volatility threshold
if CONF_VOLATILITY_THRESHOLD_MODERATE in user_input and not validate_volatility_threshold_moderate(
user_input[CONF_VOLATILITY_THRESHOLD_MODERATE]
):
errors[CONF_VOLATILITY_THRESHOLD_MODERATE] = "invalid_volatility_threshold_moderate"
# Validate high volatility threshold
if CONF_VOLATILITY_THRESHOLD_HIGH in user_input and not validate_volatility_threshold_high(
user_input[CONF_VOLATILITY_THRESHOLD_HIGH]
):
errors[CONF_VOLATILITY_THRESHOLD_HIGH] = "invalid_volatility_threshold_high"
# Validate very high volatility threshold
if CONF_VOLATILITY_THRESHOLD_VERY_HIGH in user_input and not validate_volatility_threshold_very_high(
user_input[CONF_VOLATILITY_THRESHOLD_VERY_HIGH]
):
errors[CONF_VOLATILITY_THRESHOLD_VERY_HIGH] = "invalid_volatility_threshold_very_high"
# Cross-validation: Ensure MODERATE < HIGH < VERY_HIGH
if not errors:
# Get current values directly from options (now flat)
moderate = user_input.get(
CONF_VOLATILITY_THRESHOLD_MODERATE,
self._options.get(CONF_VOLATILITY_THRESHOLD_MODERATE, DEFAULT_VOLATILITY_THRESHOLD_MODERATE),
)
high = user_input.get(
CONF_VOLATILITY_THRESHOLD_HIGH,
self._options.get(CONF_VOLATILITY_THRESHOLD_HIGH, DEFAULT_VOLATILITY_THRESHOLD_HIGH),
)
very_high = user_input.get(
CONF_VOLATILITY_THRESHOLD_VERY_HIGH,
self._options.get(CONF_VOLATILITY_THRESHOLD_VERY_HIGH, DEFAULT_VOLATILITY_THRESHOLD_VERY_HIGH),
)
if not validate_volatility_thresholds(moderate, high, very_high):
errors["base"] = "invalid_volatility_thresholds"
if not errors:
# Store flat data directly in options (no section wrapping)
self._options.update(user_input)
# async_create_entry automatically handles change detection and listener triggering
self._save_options_if_changed()
# Return to menu for more changes
return await self.async_step_init()
self._options.update(user_input)
return await self.async_step_best_price()
return self.async_show_form(
step_id="volatility",
data_schema=get_volatility_schema(self.config_entry.options),
errors=errors,
description_placeholders=self._get_entity_warning_placeholders("volatility"),
description_placeholders=self._get_step_description_placeholders("volatility"),
)

File diff suppressed because it is too large Load diff

View file

@ -1,309 +1,126 @@
"""Subentry config flow for creating time-travel views."""
"""Subentry config flow for adding additional Tibber homes."""
from __future__ import annotations
from typing import Any
import voluptuous as vol
from custom_components.tibber_prices.config_flow_handlers.schemas import (
get_select_home_schema,
get_subentry_init_schema,
)
from custom_components.tibber_prices.const import (
CONF_VIRTUAL_TIME_OFFSET_DAYS,
CONF_VIRTUAL_TIME_OFFSET_HOURS,
CONF_VIRTUAL_TIME_OFFSET_MINUTES,
CONF_EXTENDED_DESCRIPTIONS,
DEFAULT_EXTENDED_DESCRIPTIONS,
DOMAIN,
)
from homeassistant.config_entries import ConfigSubentryFlow, SubentryFlowResult
from homeassistant.helpers.selector import (
DurationSelector,
DurationSelectorConfig,
NumberSelector,
NumberSelectorConfig,
NumberSelectorMode,
SelectOptionDict,
SelectSelector,
SelectSelectorConfig,
SelectSelectorMode,
)
from homeassistant.helpers.selector import SelectOptionDict
class TibberPricesSubentryFlowHandler(ConfigSubentryFlow):
"""Handle subentry flows for tibber_prices (time-travel views)."""
def __init__(self) -> None:
"""Initialize the subentry flow handler."""
super().__init__()
self._selected_parent_entry_id: str | None = None
"""Handle subentry flows for tibber_prices."""
async def async_step_user(self, user_input: dict[str, Any] | None = None) -> SubentryFlowResult:
"""Step 1: Select which config entry should get a time-travel subentry."""
errors: dict[str, str] = {}
"""User flow to add a new home."""
parent_entry = self._get_entry()
if not parent_entry or not hasattr(parent_entry, "runtime_data") or not parent_entry.runtime_data:
return self.async_abort(reason="no_parent_entry")
coordinator = parent_entry.runtime_data.coordinator
# Force refresh user data to get latest homes from Tibber API
await coordinator.refresh_user_data()
homes = coordinator.get_user_homes()
if not homes:
return self.async_abort(reason="no_available_homes")
if user_input is not None:
self._selected_parent_entry_id = user_input["parent_entry_id"]
return await self.async_step_time_offset()
selected_home_id = user_input["home_id"]
selected_home = next((home for home in homes if home["id"] == selected_home_id), None)
# Get all main config entries (not subentries)
# Subentries have "_hist_" in their unique_id
main_entries = [
entry
for entry in self.hass.config_entries.async_entries(DOMAIN)
if entry.unique_id and "_hist_" not in entry.unique_id
]
if not selected_home:
return self.async_abort(reason="home_not_found")
if not main_entries:
return self.async_abort(reason="no_main_entries")
home_title = self._get_home_title(selected_home)
home_id = selected_home["id"]
# Build options for entry selection
entry_options = [
SelectOptionDict(
value=entry.entry_id,
label=f"{entry.title} ({entry.data.get('user_login', 'N/A')})",
return self.async_create_entry(
title=home_title,
data={
"home_id": home_id,
"home_data": selected_home,
},
description=f"Subentry for {home_title}",
description_placeholders={"home_id": home_id},
unique_id=home_id,
)
for entry in main_entries
# Get existing home IDs by checking all entries (parent + subentries)
existing_home_ids = {
entry.data["home_id"]
for entry in self.hass.config_entries.async_entries(DOMAIN)
if entry.data.get("home_id")
}
# Also include parent entry's home_id if it exists
if parent_entry.data.get("home_id"):
existing_home_ids.add(parent_entry.data["home_id"])
available_homes = [home for home in homes if home["id"] not in existing_home_ids]
if not available_homes:
return self.async_abort(reason="no_available_homes")
home_options = [
SelectOptionDict(
value=home["id"],
label=self._get_home_title(home),
)
for home in available_homes
]
return self.async_show_form(
step_id="user",
data_schema=vol.Schema(
{
vol.Required("parent_entry_id"): SelectSelector(
SelectSelectorConfig(
options=entry_options,
mode=SelectSelectorMode.DROPDOWN,
)
),
}
),
data_schema=get_select_home_schema(home_options),
description_placeholders={},
errors=errors,
errors={},
)
async def async_step_time_offset(self, user_input: dict[str, Any] | None = None) -> SubentryFlowResult:
"""Step 2: Configure time offset for the time-travel view."""
errors: dict[str, str] = {}
def _get_home_title(self, home: dict) -> str:
"""Generate a user-friendly title for a home."""
title = home.get("appNickname")
if title and title.strip():
return title.strip()
if user_input is not None:
# Extract values (convert days to int to avoid float from slider)
offset_days = int(user_input.get(CONF_VIRTUAL_TIME_OFFSET_DAYS, 0))
address = home.get("address", {})
if address:
parts = []
if address.get("address1"):
parts.append(address["address1"])
if address.get("city"):
parts.append(address["city"])
if parts:
return ", ".join(parts)
# DurationSelector returns dict with 'hours', 'minutes', and 'seconds' keys
# We normalize to minute precision (ignore seconds)
time_offset = user_input.get("time_offset", {})
offset_hours = -abs(int(time_offset.get("hours", 0))) # Always negative for historical data
offset_minutes = -abs(int(time_offset.get("minutes", 0))) # Always negative for historical data
# Note: Seconds are ignored - we only support minute-level precision
# Validate that at least one offset is negative (historical data only)
if offset_days >= 0 and offset_hours >= 0 and offset_minutes >= 0:
errors["base"] = "no_time_offset"
if not errors:
# Get parent entry
if not self._selected_parent_entry_id:
return self.async_abort(reason="parent_entry_not_found")
parent_entry = self.hass.config_entries.async_get_entry(self._selected_parent_entry_id)
if not parent_entry:
return self.async_abort(reason="parent_entry_not_found")
# Get home data from parent entry
home_id = parent_entry.data.get("home_id")
home_data = parent_entry.data.get("home_data", {})
user_login = parent_entry.data.get("user_login", "N/A")
# Build unique_id with time offset signature
offset_str = f"d{offset_days}h{offset_hours}m{offset_minutes}"
user_id = parent_entry.unique_id.split("_")[0] if parent_entry.unique_id else home_id
unique_id = f"{user_id}_{home_id}_hist_{offset_str}"
# Check if this exact time offset already exists
for entry in self.hass.config_entries.async_entries(DOMAIN):
if entry.unique_id == unique_id:
return self.async_abort(reason="already_configured")
# No duplicate found - create the entry
offset_desc = self._format_offset_description(offset_days, offset_hours, offset_minutes)
subentry_title = f"{parent_entry.title} ({offset_desc})"
# Note: Subentries inherit options from parent entry automatically
# Options parameter is not supported by ConfigSubentryFlow.async_create_entry()
return self.async_create_entry(
title=subentry_title,
data={
"home_id": home_id,
"home_data": home_data,
"user_login": user_login,
CONF_VIRTUAL_TIME_OFFSET_DAYS: offset_days,
CONF_VIRTUAL_TIME_OFFSET_HOURS: offset_hours,
CONF_VIRTUAL_TIME_OFFSET_MINUTES: offset_minutes,
},
description=f"Time-travel view: {offset_desc}",
description_placeholders={"offset": offset_desc},
unique_id=unique_id,
)
return self.async_show_form(
step_id="time_offset",
data_schema=vol.Schema(
{
vol.Required(CONF_VIRTUAL_TIME_OFFSET_DAYS, default=0): NumberSelector(
NumberSelectorConfig(
mode=NumberSelectorMode.SLIDER,
min=-374,
max=0,
step=1,
)
),
vol.Optional("time_offset", default={"hours": 0, "minutes": 0}): DurationSelector(
DurationSelectorConfig(
allow_negative=False, # We handle sign automatically
enable_day=False, # Days are handled by the slider above
)
),
}
),
description_placeholders={},
errors=errors,
)
def _format_offset_description(self, days: int, hours: int, minutes: int) -> str:
"""
Format time offset into human-readable description.
Examples:
-7, 0, 0 -> "7 days ago" (English) / "vor 7 Tagen" (German)
0, -2, 0 -> "2 hours ago" (English) / "vor 2 Stunden" (German)
-7, -2, -30 -> "7 days - 02:30" (compact format when time is added)
"""
# Get translations from custom_translations (loaded via async_load_translations)
translations_key = f"{DOMAIN}_translations_{self.hass.config.language}"
translations = self.hass.data.get(translations_key, {})
time_units = translations.get("time_units", {})
# Fallback to English if translations not available
if not time_units:
time_units = {
"day": "{count} day",
"days": "{count} days",
"hour": "{count} hour",
"hours": "{count} hours",
"minute": "{count} minute",
"minutes": "{count} minutes",
"ago": "{parts} ago",
"now": "now",
}
# Check if we have hours or minutes (need compact format)
has_time = hours != 0 or minutes != 0
if days != 0 and has_time:
# Compact format: "7 days - 02:30"
count = abs(days)
unit_key = "days" if count != 1 else "day"
day_part = time_units[unit_key].format(count=count)
time_part = f"{abs(hours):02d}:{abs(minutes):02d}"
return f"{day_part} - {time_part}"
# Standard format: separate parts with spaces
parts = []
if days != 0:
count = abs(days)
unit_key = "days" if count != 1 else "day"
parts.append(time_units[unit_key].format(count=count))
if hours != 0:
count = abs(hours)
unit_key = "hours" if count != 1 else "hour"
parts.append(time_units[unit_key].format(count=count))
if minutes != 0:
count = abs(minutes)
unit_key = "minutes" if count != 1 else "minute"
parts.append(time_units[unit_key].format(count=count))
if not parts:
return time_units.get("now", "now")
# All offsets should be negative (historical data only)
# Join parts with space and apply "ago" template
return time_units["ago"].format(parts=" ".join(parts))
return home.get("id", "Unknown Home")
async def async_step_init(self, user_input: dict | None = None) -> SubentryFlowResult:
"""Manage the options for an existing subentry (time-travel settings)."""
"""Manage the options for a subentry."""
subentry = self._get_reconfigure_subentry()
errors: dict[str, str] = {}
if user_input is not None:
# Extract values (convert days to int to avoid float from slider)
offset_days = int(user_input.get(CONF_VIRTUAL_TIME_OFFSET_DAYS, 0))
return self.async_update_and_abort(
self._get_entry(),
subentry,
data_updates=user_input,
)
# DurationSelector returns dict with 'hours', 'minutes', and 'seconds' keys
# We normalize to minute precision (ignore seconds)
time_offset = user_input.get("time_offset", {})
offset_hours = -abs(int(time_offset.get("hours", 0))) # Always negative for historical data
offset_minutes = -abs(int(time_offset.get("minutes", 0))) # Always negative for historical data
# Note: Seconds are ignored - we only support minute-level precision
# Validate that at least one offset is negative (historical data only)
if offset_days >= 0 and offset_hours >= 0 and offset_minutes >= 0:
errors["base"] = "no_time_offset"
else:
# Get parent entry to extract home_id and user_id
parent_entry = self._get_entry()
home_id = parent_entry.data.get("home_id")
# Build new unique_id with updated offset signature
offset_str = f"d{offset_days}h{offset_hours}m{offset_minutes}"
user_id = parent_entry.unique_id.split("_")[0] if parent_entry.unique_id else home_id
new_unique_id = f"{user_id}_{home_id}_hist_{offset_str}"
# Generate new title with updated offset description
offset_desc = self._format_offset_description(offset_days, offset_hours, offset_minutes)
# Extract parent title (remove old offset description in parentheses)
parent_title = parent_entry.title.split(" (")[0] if " (" in parent_entry.title else parent_entry.title
new_title = f"{parent_title} ({offset_desc})"
return self.async_update_and_abort(
parent_entry,
subentry,
unique_id=new_unique_id,
title=new_title,
data_updates=user_input,
)
offset_days = subentry.data.get(CONF_VIRTUAL_TIME_OFFSET_DAYS, 0)
offset_hours = subentry.data.get(CONF_VIRTUAL_TIME_OFFSET_HOURS, 0)
offset_minutes = subentry.data.get(CONF_VIRTUAL_TIME_OFFSET_MINUTES, 0)
# Prepare time offset dict for DurationSelector (always positive, we negate on save)
time_offset_dict = {"hours": 0, "minutes": 0} # Default to zeros
if offset_hours != 0:
time_offset_dict["hours"] = abs(offset_hours)
if offset_minutes != 0:
time_offset_dict["minutes"] = abs(offset_minutes)
extended_descriptions = subentry.data.get(CONF_EXTENDED_DESCRIPTIONS, DEFAULT_EXTENDED_DESCRIPTIONS)
return self.async_show_form(
step_id="init",
data_schema=vol.Schema(
{
vol.Required(CONF_VIRTUAL_TIME_OFFSET_DAYS, default=offset_days): NumberSelector(
NumberSelectorConfig(
mode=NumberSelectorMode.SLIDER,
min=-374,
max=0,
step=1,
)
),
vol.Optional("time_offset", default=time_offset_dict): DurationSelector(
DurationSelectorConfig(
allow_negative=False, # We handle sign automatically
enable_day=False, # Days are handled by the slider above
)
),
}
),
data_schema=get_subentry_init_schema(extended_descriptions=extended_descriptions),
errors=errors,
)

View file

@ -2,11 +2,8 @@
from __future__ import annotations
from datetime import datetime
from typing import TYPE_CHECKING, Any
import voluptuous as vol
from custom_components.tibber_prices.config_flow_handlers.options_flow import (
TibberPricesOptionsFlowHandler,
)
@ -15,17 +12,15 @@ from custom_components.tibber_prices.config_flow_handlers.schemas import (
get_select_home_schema,
get_user_schema,
)
from custom_components.tibber_prices.config_flow_handlers.subentry_flow import (
TibberPricesSubentryFlowHandler,
)
from custom_components.tibber_prices.config_flow_handlers.validators import (
TibberPricesCannotConnectError,
TibberPricesInvalidAuthError,
CannotConnectError,
InvalidAuthError,
validate_api_token,
)
from custom_components.tibber_prices.const import (
DOMAIN,
LOGGER,
get_default_options,
get_translation,
)
from custom_components.tibber_prices.const import DOMAIN, LOGGER
from homeassistant.config_entries import (
ConfigEntry,
ConfigFlow,
@ -34,18 +29,13 @@ from homeassistant.config_entries import (
)
from homeassistant.const import CONF_ACCESS_TOKEN
from homeassistant.core import callback
from homeassistant.helpers.selector import (
SelectOptionDict,
SelectSelector,
SelectSelectorConfig,
SelectSelectorMode,
)
from homeassistant.helpers.selector import SelectOptionDict
if TYPE_CHECKING:
from homeassistant.config_entries import ConfigSubentryFlow
class TibberPricesConfigFlowHandler(ConfigFlow, domain=DOMAIN):
class TibberPricesFlowHandler(ConfigFlow, domain=DOMAIN):
"""Config flow for tibber_prices."""
VERSION = 1
@ -68,12 +58,7 @@ class TibberPricesConfigFlowHandler(ConfigFlow, domain=DOMAIN):
config_entry: ConfigEntry, # noqa: ARG003
) -> dict[str, type[ConfigSubentryFlow]]:
"""Return subentries supported by this integration."""
# Temporarily disabled: Time-travel feature not yet fully implemented
# When enabled, this causes "Devices that don't belong to a sub-entry" warning
# because subentries don't have their own entities yet.
# See: https://github.com/home-assistant/core/issues/147570
# Will be re-enabled when time-travel functionality is implemented
return {}
return {"home": TibberPricesSubentryFlowHandler}
@staticmethod
@callback
@ -99,10 +84,10 @@ class TibberPricesConfigFlowHandler(ConfigFlow, domain=DOMAIN):
if user_input is not None:
try:
viewer = await validate_api_token(self.hass, user_input[CONF_ACCESS_TOKEN])
except TibberPricesInvalidAuthError as exception:
except InvalidAuthError as exception:
LOGGER.warning(exception)
_errors["base"] = "auth"
except TibberPricesCannotConnectError as exception:
except CannotConnectError as exception:
LOGGER.error(exception)
_errors["base"] = "connection"
else:
@ -141,125 +126,21 @@ class TibberPricesConfigFlowHandler(ConfigFlow, domain=DOMAIN):
step_id="reauth_confirm",
data_schema=get_reauth_confirm_schema(),
errors=_errors,
description_placeholders={"tibber_url": "https://developer.tibber.com"},
)
async def async_step_user(
self,
user_input: dict | None = None,
) -> ConfigFlowResult:
"""Handle a flow initialized by the user. Choose account or enter new token."""
# Get existing accounts
existing_entries = self.hass.config_entries.async_entries(DOMAIN)
# If there are existing accounts, offer choice
if existing_entries and user_input is None:
return await self.async_step_account_choice()
# Otherwise, go directly to token input
return await self.async_step_new_token(user_input)
async def async_step_account_choice(
self,
user_input: dict | None = None,
) -> ConfigFlowResult:
"""Let user choose between existing account or new token."""
if user_input is not None:
choice = user_input["account_choice"]
if choice == "new_token":
return await self.async_step_new_token()
# User selected an existing account - copy its token
selected_entry_id = choice
selected_entry = next(
(
entry
for entry in self.hass.config_entries.async_entries(DOMAIN)
if entry.entry_id == selected_entry_id
),
None,
)
if not selected_entry:
return self.async_abort(reason="unknown")
# Copy token from selected entry and proceed
access_token = selected_entry.data.get(CONF_ACCESS_TOKEN)
if not access_token:
return self.async_abort(reason="unknown")
return await self.async_step_new_token({CONF_ACCESS_TOKEN: access_token})
# Build options: unique user accounts (grouped by user_id) + "New Token" option
existing_entries = self.hass.config_entries.async_entries(DOMAIN)
# Group entries by user_id to show unique accounts
# Minimum parts in unique_id format: user_id_home_id
min_unique_id_parts = 2
seen_users = {}
for entry in existing_entries:
# Extract user_id from unique_id (format: user_id_home_id or user_id_home_id_sub/hist_...)
unique_id = entry.unique_id
if unique_id:
# Split by underscore and take first part as user_id
parts = unique_id.split("_")
if len(parts) >= min_unique_id_parts:
user_id = parts[0]
if user_id not in seen_users:
seen_users[user_id] = entry
# Build dropdown options from unique user accounts
account_options = [
SelectOptionDict(
value=entry.entry_id,
label=f"{entry.title} ({entry.data.get('user_login', 'N/A')})",
)
for entry in seen_users.values()
]
# Add "new_token" option with translated label
new_token_label = (
get_translation(
["selector", "account_choice", "options", "new_token"],
self.hass.config.language,
)
or "Add new Tibber account API token"
)
account_options.append(
SelectOptionDict(
value="new_token",
label=new_token_label,
)
)
return self.async_show_form(
step_id="account_choice",
data_schema=vol.Schema(
{
vol.Required("account_choice"): SelectSelector(
SelectSelectorConfig(
options=account_options,
mode=SelectSelectorMode.DROPDOWN,
)
),
}
),
)
async def async_step_new_token(
self,
user_input: dict | None = None,
) -> ConfigFlowResult:
"""Handle token input (new or copied from existing account)."""
"""Handle a flow initialized by the user. Only ask for access token."""
_errors = {}
if user_input is not None:
try:
viewer = await validate_api_token(self.hass, user_input[CONF_ACCESS_TOKEN])
except TibberPricesInvalidAuthError as exception:
except InvalidAuthError as exception:
LOGGER.warning(exception)
_errors["base"] = "auth"
except TibberPricesCannotConnectError as exception:
except CannotConnectError as exception:
LOGGER.error(exception)
_errors["base"] = "connection"
else:
@ -278,6 +159,9 @@ class TibberPricesConfigFlowHandler(ConfigFlow, domain=DOMAIN):
LOGGER.debug("Viewer data received: %s", viewer)
await self.async_set_unique_id(unique_id=str(user_id))
self._abort_if_unique_id_configured()
# Store viewer data in the flow for use in the next step
self._viewer = viewer
self._access_token = user_input[CONF_ACCESS_TOKEN]
@ -289,95 +173,25 @@ class TibberPricesConfigFlowHandler(ConfigFlow, domain=DOMAIN):
return await self.async_step_select_home()
return self.async_show_form(
step_id="new_token",
step_id="user",
data_schema=get_user_schema((user_input or {}).get(CONF_ACCESS_TOKEN)),
errors=_errors,
description_placeholders={"tibber_url": "https://developer.tibber.com"},
)
async def async_step_select_home(self, user_input: dict | None = None) -> ConfigFlowResult: # noqa: PLR0911
async def async_step_select_home(self, user_input: dict | None = None) -> ConfigFlowResult:
"""Handle home selection during initial setup."""
homes = self._viewer.get("homes", []) if self._viewer else []
if not homes:
return self.async_abort(reason="unknown")
# Filter out already configured homes
configured_home_ids = {
entry.data.get("home_id")
for entry in self.hass.config_entries.async_entries(DOMAIN)
if entry.data.get("home_id")
}
available_homes = [home for home in homes if home["id"] not in configured_home_ids]
# If no homes available, abort
if not available_homes:
return self.async_abort(reason="already_configured")
if user_input is not None:
selected_home_id = user_input["home_id"]
selected_home = next((home for home in available_homes if home["id"] == selected_home_id), None)
selected_home = next((home for home in homes if home["id"] == selected_home_id), None)
if not selected_home:
return self.async_abort(reason="unknown")
# Validate that home has an active or future subscription
subscription_status = self._get_subscription_status(selected_home)
if subscription_status == "none":
return self.async_show_form(
step_id="select_home",
data_schema=get_select_home_schema(
[
SelectOptionDict(
value=home["id"],
label=self._get_home_title_with_status(home),
)
for home in available_homes
]
),
errors={"home_id": "no_active_subscription"},
)
if subscription_status == "expired":
return self.async_show_form(
step_id="select_home",
data_schema=get_select_home_schema(
[
SelectOptionDict(
value=home["id"],
label=self._get_home_title_with_status(home),
)
for home in available_homes
]
),
errors={"home_id": "subscription_expired"},
)
# Set unique_id to user_id + home_id combination
# This allows multiple homes per user account (single-home architecture)
unique_id = f"{self._user_id}_{selected_home_id}"
await self.async_set_unique_id(unique_id)
self._abort_if_unique_id_configured()
# Note: This check is now redundant since we filter available_homes upfront,
# but kept as defensive programming in case of race conditions
for entry in self.hass.config_entries.async_entries(DOMAIN):
if entry.data.get("home_id") == selected_home_id:
return self.async_show_form(
step_id="select_home",
data_schema=get_select_home_schema(
[
SelectOptionDict(
value=home["id"],
label=self._get_home_title(home),
)
for home in available_homes
]
),
errors={"home_id": "home_already_configured"},
)
data = {
CONF_ACCESS_TOKEN: self._access_token or "",
"home_id": selected_home_id,
@ -386,32 +200,18 @@ class TibberPricesConfigFlowHandler(ConfigFlow, domain=DOMAIN):
"user_login": self._user_login or "N/A",
}
# Extract currency from home data for intelligent defaults
currency_code = None
if (
selected_home
and (subscription := selected_home.get("currentSubscription"))
and (price_info := subscription.get("priceInfo"))
and (current_price := price_info.get("current"))
):
currency_code = current_price.get("currency")
# Generate entry title from home address (not appNickname)
entry_title = self._get_entry_title(selected_home)
return self.async_create_entry(
title=entry_title,
title=self._user_name or "Unknown User",
data=data,
description=f"{self._user_login} ({self._user_id})",
options=get_default_options(currency_code),
)
home_options = [
SelectOptionDict(
value=home["id"],
label=self._get_home_title_with_status(home),
label=self._get_home_title(home),
)
for home in available_homes
for home in homes
]
return self.async_show_form(
@ -434,138 +234,9 @@ class TibberPricesConfigFlowHandler(ConfigFlow, domain=DOMAIN):
return home_ids
@staticmethod
def _get_subscription_status(home: dict) -> str:
"""
Check subscription status of home.
Returns:
- "active": Subscription is currently active
- "future": Subscription exists but starts in the future (validFrom > now)
- "expired": Subscription exists but has ended (validTo < now)
- "none": No subscription exists
"""
subscription = home.get("currentSubscription")
if subscription is None or subscription.get("status") is None:
return "none"
# Check validTo (contract end date)
valid_to = subscription.get("validTo")
if valid_to:
try:
valid_to_dt = datetime.fromisoformat(valid_to)
if valid_to_dt < datetime.now(valid_to_dt.tzinfo):
return "expired"
except (ValueError, AttributeError):
pass # If parsing fails, continue with other checks
# Check validFrom (contract start date)
valid_from = subscription.get("validFrom")
if valid_from:
try:
valid_from_dt = datetime.fromisoformat(valid_from)
if valid_from_dt > datetime.now(valid_from_dt.tzinfo):
return "future"
except (ValueError, AttributeError):
pass # If parsing fails, assume active
return "active"
def _get_home_title_with_status(self, home: dict) -> str:
"""Generate a user-friendly title for a home with subscription status."""
base_title = self._get_home_title(home)
status = self._get_subscription_status(home)
if status == "none":
return f"{base_title} ⚠️ (No active contract)"
if status == "expired":
return f"{base_title} ⚠️ (Contract expired)"
if status == "future":
return f"{base_title} ⚠️ (Contract starts soon)"
return base_title
@staticmethod
def _format_city_name(city: str) -> str:
"""
Format city name to title case.
Converts 'MÜNCHEN' to 'München', handles multi-word cities like
'BAD TÖLZ' -> 'Bad Tölz', and hyphenated cities like
'GARMISCH-PARTENKIRCHEN' -> 'Garmisch-Partenkirchen'.
"""
if not city:
return city
# Split by space and hyphen while preserving delimiters
words = []
current_word = ""
for char in city:
if char in (" ", "-"):
if current_word:
words.append(current_word)
words.append(char) # Preserve delimiter
current_word = ""
else:
current_word += char
if current_word: # Add last word
words.append(current_word)
# Capitalize first letter of each word (not delimiters)
formatted_words = []
for word in words:
if word in (" ", "-"):
formatted_words.append(word)
else:
# Capitalize first letter, lowercase rest
formatted_words.append(word.capitalize())
return "".join(formatted_words)
@staticmethod
def _get_entry_title(home: dict) -> str:
"""
Generate entry title from address (for config entry title).
Uses 'address1, City' format, e.g. 'Pählstraße 6B, München'.
Does NOT use appNickname (that's for _get_home_title).
"""
address = home.get("address", {})
if not address:
# Fallback to home ID if no address
return home.get("id", "Unknown Home")
parts = []
# Always prefer address1
address1 = address.get("address1")
if address1 and address1.strip():
parts.append(address1.strip())
# Format city name (convert MÜNCHEN -> München)
city = address.get("city")
if city and city.strip():
formatted_city = TibberPricesConfigFlowHandler._format_city_name(city.strip())
parts.append(formatted_city)
if parts:
return ", ".join(parts)
# Final fallback
return home.get("id", "Unknown Home")
@staticmethod
def _get_home_title(home: dict) -> str:
"""
Generate a user-friendly title for a home (for dropdown display).
Prefers appNickname, falls back to address.
"""
"""Generate a user-friendly title for a home."""
title = home.get("appNickname")
if title and title.strip():
return title.strip()
@ -576,10 +247,7 @@ class TibberPricesConfigFlowHandler(ConfigFlow, domain=DOMAIN):
if address.get("address1"):
parts.append(address["address1"])
if address.get("city"):
# Format city for display too
city = address["city"]
formatted_city = TibberPricesConfigFlowHandler._format_city_name(city)
parts.append(formatted_city)
parts.append(address["city"])
if parts:
return ", ".join(parts)

View file

@ -10,35 +10,7 @@ from custom_components.tibber_prices.api import (
TibberPricesApiClientCommunicationError,
TibberPricesApiClientError,
)
from custom_components.tibber_prices.const import (
DOMAIN,
MAX_DISTANCE_PERCENTAGE,
MAX_FLEX_PERCENTAGE,
MAX_GAP_COUNT,
MAX_MIN_PERIODS,
MAX_PRICE_RATING_THRESHOLD_HIGH,
MAX_PRICE_RATING_THRESHOLD_LOW,
MAX_PRICE_TREND_FALLING,
MAX_PRICE_TREND_RISING,
MAX_PRICE_TREND_STRONGLY_FALLING,
MAX_PRICE_TREND_STRONGLY_RISING,
MAX_RELAXATION_ATTEMPTS,
MAX_VOLATILITY_THRESHOLD_HIGH,
MAX_VOLATILITY_THRESHOLD_MODERATE,
MAX_VOLATILITY_THRESHOLD_VERY_HIGH,
MIN_GAP_COUNT,
MIN_PERIOD_LENGTH,
MIN_PRICE_RATING_THRESHOLD_HIGH,
MIN_PRICE_RATING_THRESHOLD_LOW,
MIN_PRICE_TREND_FALLING,
MIN_PRICE_TREND_RISING,
MIN_PRICE_TREND_STRONGLY_FALLING,
MIN_PRICE_TREND_STRONGLY_RISING,
MIN_RELAXATION_ATTEMPTS,
MIN_VOLATILITY_THRESHOLD_HIGH,
MIN_VOLATILITY_THRESHOLD_MODERATE,
MIN_VOLATILITY_THRESHOLD_VERY_HIGH,
)
from custom_components.tibber_prices.const import DOMAIN
from homeassistant.exceptions import HomeAssistantError
from homeassistant.helpers.aiohttp_client import async_create_clientsession
from homeassistant.loader import async_get_integration
@ -46,12 +18,16 @@ from homeassistant.loader import async_get_integration
if TYPE_CHECKING:
from homeassistant.core import HomeAssistant
# Constants for validation
MAX_FLEX_PERCENTAGE = 100.0
MAX_MIN_PERIODS = 10 # Arbitrary upper limit for sanity
class TibberPricesInvalidAuthError(HomeAssistantError):
class InvalidAuthError(HomeAssistantError):
"""Error to indicate invalid authentication."""
class TibberPricesCannotConnectError(HomeAssistantError):
class CannotConnectError(HomeAssistantError):
"""Error to indicate we cannot connect."""
@ -67,8 +43,8 @@ async def validate_api_token(hass: HomeAssistant, token: str) -> dict:
dict with viewer data on success
Raises:
TibberPricesInvalidAuthError: Invalid token
TibberPricesCannotConnectError: API connection failed
InvalidAuthError: Invalid token
CannotConnectError: API connection failed
"""
try:
@ -81,25 +57,41 @@ async def validate_api_token(hass: HomeAssistant, token: str) -> dict:
result = await client.async_get_viewer_details()
return result["viewer"]
except TibberPricesApiClientAuthenticationError as exception:
raise TibberPricesInvalidAuthError from exception
raise InvalidAuthError from exception
except TibberPricesApiClientCommunicationError as exception:
raise TibberPricesCannotConnectError from exception
raise CannotConnectError from exception
except TibberPricesApiClientError as exception:
raise TibberPricesCannotConnectError from exception
raise CannotConnectError from exception
def validate_threshold_range(value: float, min_val: float, max_val: float) -> bool:
"""
Validate threshold is within allowed range.
Args:
value: Value to validate
min_val: Minimum allowed value
max_val: Maximum allowed value
Returns:
True if value is within range
"""
return min_val <= value <= max_val
def validate_period_length(minutes: int) -> bool:
"""
Validate period length is a positive multiple of 15 minutes.
Validate period length is multiple of 15 minutes.
Args:
minutes: Period length in minutes
Returns:
True if length is valid (multiple of 15, at least MIN_PERIOD_LENGTH)
True if length is valid
"""
return minutes % 15 == 0 and minutes >= MIN_PERIOD_LENGTH
return minutes > 0 and minutes % 15 == 0
def validate_flex_percentage(flex: float) -> bool:
@ -107,13 +99,13 @@ def validate_flex_percentage(flex: float) -> bool:
Validate flexibility percentage is within bounds.
Args:
flex: Flexibility percentage (can be negative for peak price)
flex: Flexibility percentage
Returns:
True if percentage is valid (-MAX_FLEX to +MAX_FLEX)
True if percentage is valid
"""
return -MAX_FLEX_PERCENTAGE <= flex <= MAX_FLEX_PERCENTAGE
return 0.0 <= flex <= MAX_FLEX_PERCENTAGE
def validate_min_periods(count: int) -> bool:
@ -121,251 +113,10 @@ def validate_min_periods(count: int) -> bool:
Validate minimum periods count is reasonable.
Args:
count: Number of minimum periods per day
count: Number of minimum periods
Returns:
True if count is valid (1 to MAX_MIN_PERIODS)
True if count is valid
"""
return 1 <= count <= MAX_MIN_PERIODS
def validate_distance_percentage(distance: float) -> bool:
"""
Validate distance from average percentage (for Peak Price - positive values).
Args:
distance: Distance percentage (0-50% is typical range)
Returns:
True if distance is valid (0-MAX_DISTANCE_PERCENTAGE)
"""
return 0.0 <= distance <= MAX_DISTANCE_PERCENTAGE
def validate_best_price_distance_percentage(distance: float) -> bool:
"""
Validate distance from average percentage (for Best Price - negative values).
Args:
distance: Distance percentage (-50% to 0% range, negative = below average)
Returns:
True if distance is valid (-MAX_DISTANCE_PERCENTAGE to 0)
"""
return -MAX_DISTANCE_PERCENTAGE <= distance <= 0.0
def validate_gap_count(count: int) -> bool:
"""
Validate gap count is within bounds.
Args:
count: Gap count (0-8)
Returns:
True if count is valid (MIN_GAP_COUNT to MAX_GAP_COUNT)
"""
return MIN_GAP_COUNT <= count <= MAX_GAP_COUNT
def validate_relaxation_attempts(attempts: int) -> bool:
"""
Validate relaxation attempts count is within bounds.
Args:
attempts: Number of relaxation attempts (1-12)
Returns:
True if attempts is valid (MIN_RELAXATION_ATTEMPTS to MAX_RELAXATION_ATTEMPTS)
"""
return MIN_RELAXATION_ATTEMPTS <= attempts <= MAX_RELAXATION_ATTEMPTS
def validate_price_rating_threshold_low(threshold: int) -> bool:
"""
Validate low price rating threshold.
Args:
threshold: Low rating threshold percentage (-50 to -5)
Returns:
True if threshold is valid (MIN_PRICE_RATING_THRESHOLD_LOW to MAX_PRICE_RATING_THRESHOLD_LOW)
"""
return MIN_PRICE_RATING_THRESHOLD_LOW <= threshold <= MAX_PRICE_RATING_THRESHOLD_LOW
def validate_price_rating_threshold_high(threshold: int) -> bool:
"""
Validate high price rating threshold.
Args:
threshold: High rating threshold percentage (5 to 50)
Returns:
True if threshold is valid (MIN_PRICE_RATING_THRESHOLD_HIGH to MAX_PRICE_RATING_THRESHOLD_HIGH)
"""
return MIN_PRICE_RATING_THRESHOLD_HIGH <= threshold <= MAX_PRICE_RATING_THRESHOLD_HIGH
def validate_price_rating_thresholds(threshold_low: int, threshold_high: int) -> bool:
"""
Cross-validate both price rating thresholds together.
Ensures that LOW threshold < HIGH threshold with proper gap to avoid
overlap at 0%. LOW should be negative (below average), HIGH should be
positive (above average).
Args:
threshold_low: Low rating threshold percentage (-50 to -5)
threshold_high: High rating threshold percentage (5 to 50)
Returns:
True if both thresholds are valid individually AND threshold_low < threshold_high
"""
# Validate individual ranges first
if not validate_price_rating_threshold_low(threshold_low):
return False
if not validate_price_rating_threshold_high(threshold_high):
return False
# Ensure LOW is always less than HIGH (should always be true given the ranges,
# but explicit check for safety)
return threshold_low < threshold_high
def validate_volatility_threshold_moderate(threshold: float) -> bool:
"""
Validate moderate volatility threshold.
Args:
threshold: Moderate volatility threshold percentage (5.0 to 25.0)
Returns:
True if threshold is valid (MIN_VOLATILITY_THRESHOLD_MODERATE to MAX_VOLATILITY_THRESHOLD_MODERATE)
"""
return MIN_VOLATILITY_THRESHOLD_MODERATE <= threshold <= MAX_VOLATILITY_THRESHOLD_MODERATE
def validate_volatility_threshold_high(threshold: float) -> bool:
"""
Validate high volatility threshold.
Args:
threshold: High volatility threshold percentage (20.0 to 40.0)
Returns:
True if threshold is valid (MIN_VOLATILITY_THRESHOLD_HIGH to MAX_VOLATILITY_THRESHOLD_HIGH)
"""
return MIN_VOLATILITY_THRESHOLD_HIGH <= threshold <= MAX_VOLATILITY_THRESHOLD_HIGH
def validate_volatility_threshold_very_high(threshold: float) -> bool:
"""
Validate very high volatility threshold.
Args:
threshold: Very high volatility threshold percentage (35.0 to 80.0)
Returns:
True if threshold is valid (MIN_VOLATILITY_THRESHOLD_VERY_HIGH to MAX_VOLATILITY_THRESHOLD_VERY_HIGH)
"""
return MIN_VOLATILITY_THRESHOLD_VERY_HIGH <= threshold <= MAX_VOLATILITY_THRESHOLD_VERY_HIGH
def validate_volatility_thresholds(
threshold_moderate: float,
threshold_high: float,
threshold_very_high: float,
) -> bool:
"""
Cross-validate all three volatility thresholds together.
Ensures that MODERATE < HIGH < VERY_HIGH to maintain logical classification
boundaries. Each threshold represents an escalating level of price volatility.
Args:
threshold_moderate: Moderate volatility threshold (5.0 to 25.0)
threshold_high: High volatility threshold (20.0 to 40.0)
threshold_very_high: Very high volatility threshold (35.0 to 80.0)
Returns:
True if all thresholds are valid individually AND maintain proper ordering
"""
# Validate individual ranges first
if not validate_volatility_threshold_moderate(threshold_moderate):
return False
if not validate_volatility_threshold_high(threshold_high):
return False
if not validate_volatility_threshold_very_high(threshold_very_high):
return False
# Ensure cascading order: MODERATE < HIGH < VERY_HIGH
return threshold_moderate < threshold_high < threshold_very_high
def validate_price_trend_rising(threshold: int) -> bool:
"""
Validate rising price trend threshold.
Args:
threshold: Rising trend threshold percentage (1 to 50)
Returns:
True if threshold is valid (MIN_PRICE_TREND_RISING to MAX_PRICE_TREND_RISING)
"""
return MIN_PRICE_TREND_RISING <= threshold <= MAX_PRICE_TREND_RISING
def validate_price_trend_falling(threshold: int) -> bool:
"""
Validate falling price trend threshold.
Args:
threshold: Falling trend threshold percentage (-50 to -1)
Returns:
True if threshold is valid (MIN_PRICE_TREND_FALLING to MAX_PRICE_TREND_FALLING)
"""
return MIN_PRICE_TREND_FALLING <= threshold <= MAX_PRICE_TREND_FALLING
def validate_price_trend_strongly_rising(threshold: int) -> bool:
"""
Validate strongly rising price trend threshold.
Args:
threshold: Strongly rising trend threshold percentage (2 to 100)
Returns:
True if threshold is valid (MIN_PRICE_TREND_STRONGLY_RISING to MAX_PRICE_TREND_STRONGLY_RISING)
"""
return MIN_PRICE_TREND_STRONGLY_RISING <= threshold <= MAX_PRICE_TREND_STRONGLY_RISING
def validate_price_trend_strongly_falling(threshold: int) -> bool:
"""
Validate strongly falling price trend threshold.
Args:
threshold: Strongly falling trend threshold percentage (-100 to -2)
Returns:
True if threshold is valid (MIN_PRICE_TREND_STRONGLY_FALLING to MAX_PRICE_TREND_STRONGLY_FALLING)
"""
return MIN_PRICE_TREND_STRONGLY_FALLING <= threshold <= MAX_PRICE_TREND_STRONGLY_FALLING
return count > 0 and count <= MAX_MIN_PERIODS

View file

@ -1,11 +1,10 @@
"""Constants for the Tibber Price Analytics integration."""
from __future__ import annotations
import json
import logging
from collections.abc import Sequence
from pathlib import Path
from typing import TYPE_CHECKING, Any
from typing import Any
import aiofiles
@ -15,27 +14,15 @@ from homeassistant.const import (
UnitOfPower,
UnitOfTime,
)
if TYPE_CHECKING:
from collections.abc import Sequence
from homeassistant.config_entries import ConfigEntry
from homeassistant.core import HomeAssistant
from homeassistant.core import HomeAssistant
DOMAIN = "tibber_prices"
LOGGER = logging.getLogger(__package__)
# Data storage keys
DATA_CHART_CONFIG = "chart_config" # Key for chart export config in hass.data
DATA_CHART_METADATA_CONFIG = "chart_metadata_config" # Key for chart metadata config in hass.data
# Time constants
MINUTES_PER_INTERVAL = 15 # Tibber uses 15-minute intervals for price data
# Configuration keys
CONF_EXTENDED_DESCRIPTIONS = "extended_descriptions"
CONF_VIRTUAL_TIME_OFFSET_DAYS = (
"virtual_time_offset_days" # Time-travel: days offset (negative only, e.g., -7 = 7 days ago)
)
CONF_VIRTUAL_TIME_OFFSET_HOURS = "virtual_time_offset_hours" # Time-travel: hours offset (-23 to +23)
CONF_VIRTUAL_TIME_OFFSET_MINUTES = "virtual_time_offset_minutes" # Time-travel: minutes offset (-59 to +59)
CONF_BEST_PRICE_FLEX = "best_price_flex"
CONF_PEAK_PRICE_FLEX = "peak_price_flex"
CONF_BEST_PRICE_MIN_DISTANCE_FROM_AVG = "best_price_min_distance_from_avg"
@ -44,14 +31,8 @@ CONF_BEST_PRICE_MIN_PERIOD_LENGTH = "best_price_min_period_length"
CONF_PEAK_PRICE_MIN_PERIOD_LENGTH = "peak_price_min_period_length"
CONF_PRICE_RATING_THRESHOLD_LOW = "price_rating_threshold_low"
CONF_PRICE_RATING_THRESHOLD_HIGH = "price_rating_threshold_high"
CONF_PRICE_RATING_HYSTERESIS = "price_rating_hysteresis"
CONF_PRICE_RATING_GAP_TOLERANCE = "price_rating_gap_tolerance"
CONF_PRICE_LEVEL_GAP_TOLERANCE = "price_level_gap_tolerance"
CONF_AVERAGE_SENSOR_DISPLAY = "average_sensor_display" # "median" or "mean"
CONF_PRICE_TREND_THRESHOLD_RISING = "price_trend_threshold_rising"
CONF_PRICE_TREND_THRESHOLD_FALLING = "price_trend_threshold_falling"
CONF_PRICE_TREND_THRESHOLD_STRONGLY_RISING = "price_trend_threshold_strongly_rising"
CONF_PRICE_TREND_THRESHOLD_STRONGLY_FALLING = "price_trend_threshold_strongly_falling"
CONF_VOLATILITY_THRESHOLD_MODERATE = "volatility_threshold_moderate"
CONF_VOLATILITY_THRESHOLD_HIGH = "volatility_threshold_high"
CONF_VOLATILITY_THRESHOLD_VERY_HIGH = "volatility_threshold_very_high"
@ -61,9 +42,11 @@ CONF_BEST_PRICE_MAX_LEVEL_GAP_COUNT = "best_price_max_level_gap_count"
CONF_PEAK_PRICE_MAX_LEVEL_GAP_COUNT = "peak_price_max_level_gap_count"
CONF_ENABLE_MIN_PERIODS_BEST = "enable_min_periods_best"
CONF_MIN_PERIODS_BEST = "min_periods_best"
CONF_RELAXATION_STEP_BEST = "relaxation_step_best"
CONF_RELAXATION_ATTEMPTS_BEST = "relaxation_attempts_best"
CONF_ENABLE_MIN_PERIODS_PEAK = "enable_min_periods_peak"
CONF_MIN_PERIODS_PEAK = "min_periods_peak"
CONF_RELAXATION_STEP_PEAK = "relaxation_step_peak"
CONF_RELAXATION_ATTEMPTS_PEAK = "relaxation_attempts_peak"
CONF_CHART_DATA_CONFIG = "chart_data_config" # YAML config for chart data export
@ -72,23 +55,16 @@ ATTRIBUTION = "Data provided by Tibber"
# Integration name should match manifest.json
DEFAULT_NAME = "Tibber Price Information & Ratings"
DEFAULT_EXTENDED_DESCRIPTIONS = False
DEFAULT_VIRTUAL_TIME_OFFSET_DAYS = 0 # No time offset (live mode)
DEFAULT_VIRTUAL_TIME_OFFSET_HOURS = 0
DEFAULT_VIRTUAL_TIME_OFFSET_MINUTES = 0
DEFAULT_BEST_PRICE_FLEX = 15 # 15% base flexibility - optimal for relaxation mode (default enabled)
# Peak price flexibility is set to -20% (20% base flexibility - optimal for relaxation mode).
DEFAULT_BEST_PRICE_FLEX = 15 # 15% flexibility for best price (user-facing, percent)
# Peak price flexibility is set to -20 (20%) to allow for more adaptive detection of expensive periods.
# This is intentionally more flexible than best price (15%) because peak price periods can be more variable,
# and users may benefit from earlier warnings about expensive periods, even if they are less sharply defined.
# The negative sign indicates that the threshold is set below the MAX price
# (e.g., -20% means MAX * 0.8), not above the average price.
# A higher percentage allows for more conservative detection, reducing false negatives for peak price warnings.
DEFAULT_PEAK_PRICE_FLEX = -20 # 20% base flexibility (user-facing, percent)
DEFAULT_BEST_PRICE_MIN_DISTANCE_FROM_AVG = (
-5
) # -5% minimum distance from daily average (below average, ensures significance)
DEFAULT_PEAK_PRICE_MIN_DISTANCE_FROM_AVG = (
5 # 5% minimum distance from daily average (above average, ensures significance)
)
DEFAULT_PEAK_PRICE_FLEX = -20 # 20% flexibility for peak price (user-facing, percent)
DEFAULT_BEST_PRICE_MIN_DISTANCE_FROM_AVG = 5 # 5% minimum distance from daily average (ensures significance)
DEFAULT_PEAK_PRICE_MIN_DISTANCE_FROM_AVG = 5 # 5% minimum distance from daily average (ensures significance)
DEFAULT_BEST_PRICE_MIN_PERIOD_LENGTH = 60 # 60 minutes minimum period length for best price (user-facing, minutes)
# Note: Peak price warnings are allowed for shorter periods (30 min) than best price periods (60 min).
# This asymmetry is intentional: shorter peak periods are acceptable for alerting users to brief expensive spikes,
@ -97,16 +73,8 @@ DEFAULT_BEST_PRICE_MIN_PERIOD_LENGTH = 60 # 60 minutes minimum period length fo
DEFAULT_PEAK_PRICE_MIN_PERIOD_LENGTH = 30 # 30 minutes minimum period length for peak price (user-facing, minutes)
DEFAULT_PRICE_RATING_THRESHOLD_LOW = -10 # Default rating threshold low percentage
DEFAULT_PRICE_RATING_THRESHOLD_HIGH = 10 # Default rating threshold high percentage
DEFAULT_PRICE_RATING_HYSTERESIS = 2.0 # Hysteresis percentage to prevent flickering at threshold boundaries
DEFAULT_PRICE_RATING_GAP_TOLERANCE = 1 # Max consecutive intervals to smooth out (0 = disabled)
DEFAULT_PRICE_LEVEL_GAP_TOLERANCE = 1 # Max consecutive intervals to smooth out for price level (0 = disabled)
DEFAULT_AVERAGE_SENSOR_DISPLAY = "median" # Default: show median in state, mean in attributes
DEFAULT_PRICE_TREND_THRESHOLD_RISING = 3 # Default trend threshold for rising prices (%)
DEFAULT_PRICE_TREND_THRESHOLD_FALLING = -3 # Default trend threshold for falling prices (%, negative value)
# Strong trend thresholds default to 2x the base threshold.
# These are independently configurable to allow fine-tuning of "strongly" detection.
DEFAULT_PRICE_TREND_THRESHOLD_STRONGLY_RISING = 6 # Default strong rising threshold (%)
DEFAULT_PRICE_TREND_THRESHOLD_STRONGLY_FALLING = -6 # Default strong falling threshold (%, negative value)
# Default volatility thresholds (relative values using coefficient of variation)
# Coefficient of variation = (standard_deviation / mean) * 100%
# These thresholds are unitless and work across different price levels
@ -120,62 +88,12 @@ DEFAULT_PEAK_PRICE_MAX_LEVEL_GAP_COUNT = 1 # Default: allow 1 level gap for pea
MIN_INTERVALS_FOR_GAP_TOLERANCE = 6 # Minimum period length (in 15-min intervals = 1.5h) required for gap tolerance
DEFAULT_ENABLE_MIN_PERIODS_BEST = True # Default: minimum periods feature enabled for best price
DEFAULT_MIN_PERIODS_BEST = 2 # Default: require at least 2 best price periods (when enabled)
DEFAULT_RELAXATION_ATTEMPTS_BEST = 11 # Default: 11 steps allows escalation from 15% to 48% (3% increment per step)
DEFAULT_RELAXATION_STEP_BEST = 25 # Default: 25% of original threshold per relaxation step for best price
DEFAULT_RELAXATION_ATTEMPTS_BEST = 8 # Default: try 8 flex levels during relaxation (best price)
DEFAULT_ENABLE_MIN_PERIODS_PEAK = True # Default: minimum periods feature enabled for peak price
DEFAULT_MIN_PERIODS_PEAK = 2 # Default: require at least 2 peak price periods (when enabled)
DEFAULT_RELAXATION_ATTEMPTS_PEAK = 11 # Default: 11 steps allows escalation from 20% to 50% (3% increment per step)
# Validation limits (used in GUI schemas and server-side validation)
# These ensure consistency between frontend and backend validation
MAX_FLEX_PERCENTAGE = 50 # Maximum flexibility percentage (aligned with GUI slider and MAX_SAFE_FLEX)
MAX_DISTANCE_PERCENTAGE = 50 # Maximum distance from average percentage (GUI slider limit)
MAX_GAP_COUNT = 8 # Maximum gap count for level filtering (GUI slider limit)
MAX_MIN_PERIODS = 10 # Maximum number of minimum periods per day (GUI slider limit)
MAX_RELAXATION_ATTEMPTS = 12 # Maximum relaxation attempts (GUI slider limit)
MIN_PERIOD_LENGTH = 15 # Minimum period length in minutes (1 quarter hour)
MAX_MIN_PERIOD_LENGTH = 180 # Maximum for minimum period length setting (3 hours - realistic for required minimum)
# Price rating threshold limits
# LOW threshold: negative values (prices below average) - practical range -50% to -5%
# HIGH threshold: positive values (prices above average) - practical range +5% to +50%
# Ensure minimum 5% gap between thresholds to avoid overlap at 0%
MIN_PRICE_RATING_THRESHOLD_LOW = -50 # Minimum value for low rating threshold
MAX_PRICE_RATING_THRESHOLD_LOW = -5 # Maximum value for low rating threshold (must be < HIGH)
MIN_PRICE_RATING_THRESHOLD_HIGH = 5 # Minimum value for high rating threshold (must be > LOW)
MAX_PRICE_RATING_THRESHOLD_HIGH = 50 # Maximum value for high rating threshold
MIN_PRICE_RATING_HYSTERESIS = 0.0 # Minimum hysteresis (0 = disabled)
MAX_PRICE_RATING_HYSTERESIS = 5.0 # Maximum hysteresis (5% band)
MIN_PRICE_RATING_GAP_TOLERANCE = 0 # Minimum gap tolerance (0 = disabled)
MAX_PRICE_RATING_GAP_TOLERANCE = 4 # Maximum gap tolerance (4 intervals = 1 hour)
MIN_PRICE_LEVEL_GAP_TOLERANCE = 0 # Minimum gap tolerance for price level (0 = disabled)
MAX_PRICE_LEVEL_GAP_TOLERANCE = 4 # Maximum gap tolerance for price level (4 intervals = 1 hour)
# Volatility threshold limits
# MODERATE threshold: practical range 5% to 25% (entry point for noticeable fluctuation)
# HIGH threshold: practical range 20% to 40% (significant price swings)
# VERY_HIGH threshold: practical range 35% to 80% (extreme volatility)
# Ensure cascading: MODERATE < HIGH < VERY_HIGH with ~5% minimum gaps
MIN_VOLATILITY_THRESHOLD_MODERATE = 5.0 # Minimum for moderate volatility threshold
MAX_VOLATILITY_THRESHOLD_MODERATE = 25.0 # Maximum for moderate volatility threshold (must be < HIGH)
MIN_VOLATILITY_THRESHOLD_HIGH = 20.0 # Minimum for high volatility threshold (must be > MODERATE)
MAX_VOLATILITY_THRESHOLD_HIGH = 40.0 # Maximum for high volatility threshold (must be < VERY_HIGH)
MIN_VOLATILITY_THRESHOLD_VERY_HIGH = 35.0 # Minimum for very high volatility threshold (must be > HIGH)
MAX_VOLATILITY_THRESHOLD_VERY_HIGH = 80.0 # Maximum for very high volatility threshold
# Price trend threshold limits
MIN_PRICE_TREND_RISING = 1 # Minimum rising trend threshold
MAX_PRICE_TREND_RISING = 50 # Maximum rising trend threshold
MIN_PRICE_TREND_FALLING = -50 # Minimum falling trend threshold (negative)
MAX_PRICE_TREND_FALLING = -1 # Maximum falling trend threshold (negative)
# Strong trend thresholds have higher ranges to allow detection of significant moves
MIN_PRICE_TREND_STRONGLY_RISING = 2 # Minimum strongly rising threshold (must be > rising)
MAX_PRICE_TREND_STRONGLY_RISING = 100 # Maximum strongly rising threshold
MIN_PRICE_TREND_STRONGLY_FALLING = -100 # Minimum strongly falling threshold (negative)
MAX_PRICE_TREND_STRONGLY_FALLING = -2 # Maximum strongly falling threshold (must be < falling)
# Gap count and relaxation limits
MIN_GAP_COUNT = 0 # Minimum gap count
MIN_RELAXATION_ATTEMPTS = 1 # Minimum relaxation attempts
DEFAULT_RELAXATION_STEP_PEAK = 25 # Default: 25% of original threshold per relaxation step for peak price
DEFAULT_RELAXATION_ATTEMPTS_PEAK = 8 # Default: try 8 flex levels during relaxation (peak price)
# Home types
HOME_TYPE_APARTMENT = "APARTMENT"
@ -194,22 +112,12 @@ HOME_TYPES = {
# Currency mapping: ISO code -> (major_symbol, minor_symbol, minor_name)
# For currencies with Home Assistant constants, use those; otherwise define custom ones
CURRENCY_INFO = {
"EUR": (CURRENCY_EURO, "ct", "Cents"),
"NOK": ("kr", "øre", "Øre"),
"SEK": ("kr", "öre", "Öre"),
"DKK": ("kr", "øre", "Øre"),
"USD": (CURRENCY_DOLLAR, "¢", "Cents"),
"GBP": ("£", "p", "Pence"),
}
# Base currency names: ISO code -> full currency name (in local language)
CURRENCY_NAMES = {
"EUR": "Euro",
"NOK": "Norske kroner",
"SEK": "Svenska kronor",
"DKK": "Danske kroner",
"USD": "US Dollar",
"GBP": "British Pound",
"EUR": (CURRENCY_EURO, "ct", "cents"),
"NOK": ("kr", "øre", "øre"),
"SEK": ("kr", "öre", "öre"),
"DKK": ("kr", "øre", "øre"),
"USD": (CURRENCY_DOLLAR, "¢", "cents"),
"GBP": ("£", "p", "pence"),
}
@ -231,9 +139,9 @@ def get_currency_info(currency_code: str | None) -> tuple[str, str, str]:
return CURRENCY_INFO.get(currency_code.upper(), CURRENCY_INFO["EUR"])
def format_price_unit_base(currency_code: str | None) -> str:
def format_price_unit_major(currency_code: str | None) -> str:
"""
Format the price unit string with base currency unit (e.g., '€/kWh').
Format the price unit string with major currency unit (e.g., '€/kWh').
Args:
currency_code: ISO 4217 currency code (e.g., 'EUR', 'NOK', 'SEK')
@ -242,13 +150,13 @@ def format_price_unit_base(currency_code: str | None) -> str:
Formatted unit string like '€/kWh' or 'kr/kWh'
"""
base_symbol, _, _ = get_currency_info(currency_code)
return f"{base_symbol}/{UnitOfPower.KILO_WATT}{UnitOfTime.HOURS}"
major_symbol, _, _ = get_currency_info(currency_code)
return f"{major_symbol}/{UnitOfPower.KILO_WATT}{UnitOfTime.HOURS}"
def format_price_unit_subunit(currency_code: str | None) -> str:
def format_price_unit_minor(currency_code: str | None) -> str:
"""
Format the price unit string with subunit currency unit (e.g., 'ct/kWh').
Format the price unit string with minor currency unit (e.g., 'ct/kWh').
Args:
currency_code: ISO 4217 currency code (e.g., 'EUR', 'NOK', 'SEK')
@ -257,190 +165,11 @@ def format_price_unit_subunit(currency_code: str | None) -> str:
Formatted unit string like 'ct/kWh' or 'øre/kWh'
"""
_, subunit_symbol, _ = get_currency_info(currency_code)
return f"{subunit_symbol}/{UnitOfPower.KILO_WATT}{UnitOfTime.HOURS}"
_, minor_symbol, _ = get_currency_info(currency_code)
return f"{minor_symbol}/{UnitOfPower.KILO_WATT}{UnitOfTime.HOURS}"
def get_currency_name(currency_code: str | None) -> str:
"""
Get the full name of the base currency.
Args:
currency_code: ISO 4217 currency code (e.g., 'EUR', 'NOK', 'SEK')
Returns:
Full currency name like 'Euro' or 'Norwegian Krone'
Defaults to 'Euro' if currency is not recognized
"""
if not currency_code:
currency_code = "EUR"
return CURRENCY_NAMES.get(currency_code.upper(), CURRENCY_NAMES["EUR"])
# ============================================================================
# Currency Display Mode Configuration
# ============================================================================
# Configuration key for currency display mode
CONF_CURRENCY_DISPLAY_MODE = "currency_display_mode"
# Display mode values
DISPLAY_MODE_BASE = "base" # Display in base currency units (€, kr)
DISPLAY_MODE_SUBUNIT = "subunit" # Display in subunit currency units (ct, øre)
# Intelligent per-currency defaults based on market analysis
# EUR: Subunit (cents) - established convention in Germany/Netherlands
# NOK/SEK/DKK: Base (kroner) - Scandinavian preference for whole units
# USD/GBP: Base - international standard
DEFAULT_CURRENCY_DISPLAY = {
"EUR": DISPLAY_MODE_SUBUNIT,
"NOK": DISPLAY_MODE_BASE,
"SEK": DISPLAY_MODE_BASE,
"DKK": DISPLAY_MODE_BASE,
"USD": DISPLAY_MODE_BASE,
"GBP": DISPLAY_MODE_BASE,
}
def get_default_currency_display(currency_code: str | None) -> str:
"""
Get intelligent default display mode for a currency.
Args:
currency_code: ISO 4217 currency code (e.g., 'EUR', 'NOK')
Returns:
Default display mode ('base' or 'subunit')
"""
if not currency_code:
return DISPLAY_MODE_SUBUNIT # Fallback default
return DEFAULT_CURRENCY_DISPLAY.get(currency_code.upper(), DISPLAY_MODE_SUBUNIT)
def get_default_options(currency_code: str | None) -> dict[str, Any]:
"""
Get complete default options for a new config entry.
This ensures new config entries have explicitly set defaults based on their currency,
distinguishing them from legacy config entries that need migration.
Options structure has been flattened for single-section steps:
- Flat values: extended_descriptions, average_sensor_display, currency_display_mode,
price_rating_thresholds, volatility_thresholds, price_trend_thresholds, time offsets
- Nested sections (multi-section steps only): period_settings, flexibility_settings,
relaxation_and_target_periods
Args:
currency_code: ISO 4217 currency code (e.g., 'EUR', 'NOK')
Returns:
Dictionary with all default option values in nested section structure
"""
return {
# Flat configuration values
CONF_EXTENDED_DESCRIPTIONS: DEFAULT_EXTENDED_DESCRIPTIONS,
CONF_AVERAGE_SENSOR_DISPLAY: DEFAULT_AVERAGE_SENSOR_DISPLAY,
CONF_CURRENCY_DISPLAY_MODE: get_default_currency_display(currency_code),
CONF_VIRTUAL_TIME_OFFSET_DAYS: DEFAULT_VIRTUAL_TIME_OFFSET_DAYS,
CONF_VIRTUAL_TIME_OFFSET_HOURS: DEFAULT_VIRTUAL_TIME_OFFSET_HOURS,
CONF_VIRTUAL_TIME_OFFSET_MINUTES: DEFAULT_VIRTUAL_TIME_OFFSET_MINUTES,
# Price rating settings (flat - single-section step)
CONF_PRICE_RATING_THRESHOLD_LOW: DEFAULT_PRICE_RATING_THRESHOLD_LOW,
CONF_PRICE_RATING_THRESHOLD_HIGH: DEFAULT_PRICE_RATING_THRESHOLD_HIGH,
CONF_PRICE_RATING_HYSTERESIS: DEFAULT_PRICE_RATING_HYSTERESIS,
CONF_PRICE_RATING_GAP_TOLERANCE: DEFAULT_PRICE_RATING_GAP_TOLERANCE,
CONF_PRICE_LEVEL_GAP_TOLERANCE: DEFAULT_PRICE_LEVEL_GAP_TOLERANCE,
# Volatility thresholds (flat - single-section step)
CONF_VOLATILITY_THRESHOLD_MODERATE: DEFAULT_VOLATILITY_THRESHOLD_MODERATE,
CONF_VOLATILITY_THRESHOLD_HIGH: DEFAULT_VOLATILITY_THRESHOLD_HIGH,
CONF_VOLATILITY_THRESHOLD_VERY_HIGH: DEFAULT_VOLATILITY_THRESHOLD_VERY_HIGH,
# Price trend thresholds (flat - single-section step)
CONF_PRICE_TREND_THRESHOLD_RISING: DEFAULT_PRICE_TREND_THRESHOLD_RISING,
CONF_PRICE_TREND_THRESHOLD_FALLING: DEFAULT_PRICE_TREND_THRESHOLD_FALLING,
# Nested section: Period settings (shared by best/peak price)
"period_settings": {
CONF_BEST_PRICE_MIN_PERIOD_LENGTH: DEFAULT_BEST_PRICE_MIN_PERIOD_LENGTH,
CONF_PEAK_PRICE_MIN_PERIOD_LENGTH: DEFAULT_PEAK_PRICE_MIN_PERIOD_LENGTH,
CONF_BEST_PRICE_MAX_LEVEL_GAP_COUNT: DEFAULT_BEST_PRICE_MAX_LEVEL_GAP_COUNT,
CONF_PEAK_PRICE_MAX_LEVEL_GAP_COUNT: DEFAULT_PEAK_PRICE_MAX_LEVEL_GAP_COUNT,
CONF_BEST_PRICE_MAX_LEVEL: DEFAULT_BEST_PRICE_MAX_LEVEL,
CONF_PEAK_PRICE_MIN_LEVEL: DEFAULT_PEAK_PRICE_MIN_LEVEL,
},
# Nested section: Flexibility settings (shared by best/peak price)
"flexibility_settings": {
CONF_BEST_PRICE_FLEX: DEFAULT_BEST_PRICE_FLEX,
CONF_PEAK_PRICE_FLEX: DEFAULT_PEAK_PRICE_FLEX,
CONF_BEST_PRICE_MIN_DISTANCE_FROM_AVG: DEFAULT_BEST_PRICE_MIN_DISTANCE_FROM_AVG,
CONF_PEAK_PRICE_MIN_DISTANCE_FROM_AVG: DEFAULT_PEAK_PRICE_MIN_DISTANCE_FROM_AVG,
},
# Nested section: Relaxation and target periods (shared by best/peak price)
"relaxation_and_target_periods": {
CONF_ENABLE_MIN_PERIODS_BEST: DEFAULT_ENABLE_MIN_PERIODS_BEST,
CONF_MIN_PERIODS_BEST: DEFAULT_MIN_PERIODS_BEST,
CONF_RELAXATION_ATTEMPTS_BEST: DEFAULT_RELAXATION_ATTEMPTS_BEST,
CONF_ENABLE_MIN_PERIODS_PEAK: DEFAULT_ENABLE_MIN_PERIODS_PEAK,
CONF_MIN_PERIODS_PEAK: DEFAULT_MIN_PERIODS_PEAK,
CONF_RELAXATION_ATTEMPTS_PEAK: DEFAULT_RELAXATION_ATTEMPTS_PEAK,
},
}
def get_display_unit_factor(config_entry: ConfigEntry) -> int:
"""
Get multiplication factor for converting base to display currency.
Internal storage is ALWAYS in base currency (4 decimals precision).
This function returns the conversion factor based on user configuration.
Args:
config_entry: ConfigEntry with currency_display_mode option
Returns:
100 for subunit currency display, 1 for base currency display
Example:
price_base = 0.2534 # Internal: 0.2534 €/kWh
factor = get_display_unit_factor(config_entry)
display_value = round(price_base * factor, 2)
# → 25.34 ct/kWh (subunit) or 0.25 €/kWh (base)
"""
display_mode = config_entry.options.get(CONF_CURRENCY_DISPLAY_MODE, DISPLAY_MODE_SUBUNIT)
return 100 if display_mode == DISPLAY_MODE_SUBUNIT else 1
def get_display_unit_string(config_entry: ConfigEntry, currency_code: str | None) -> str:
"""
Get unit string for display based on configuration.
Args:
config_entry: ConfigEntry with currency_display_mode option
currency_code: ISO 4217 currency code
Returns:
Formatted unit string (e.g., 'ct/kWh' or '€/kWh')
"""
display_mode = config_entry.options.get(CONF_CURRENCY_DISPLAY_MODE, DISPLAY_MODE_SUBUNIT)
if display_mode == DISPLAY_MODE_SUBUNIT:
return format_price_unit_subunit(currency_code)
return format_price_unit_base(currency_code)
# ============================================================================
# Price Level, Rating, and Volatility Constants
# ============================================================================
# IMPORTANT: These string constants are the single source of truth for
# valid enum values. The Literal types in sensor/types.py and binary_sensor/types.py
# should be kept in sync with these values manually.
# Price level constants (from Tibber API)
# Price level constants from Tibber API
PRICE_LEVEL_VERY_CHEAP = "VERY_CHEAP"
PRICE_LEVEL_CHEAP = "CHEAP"
PRICE_LEVEL_NORMAL = "NORMAL"
@ -452,20 +181,12 @@ PRICE_RATING_LOW = "LOW"
PRICE_RATING_NORMAL = "NORMAL"
PRICE_RATING_HIGH = "HIGH"
# Price volatility level constants
# Price volatility levels (based on coefficient of variation: std_dev / mean * 100%)
VOLATILITY_LOW = "LOW"
VOLATILITY_MODERATE = "MODERATE"
VOLATILITY_HIGH = "HIGH"
VOLATILITY_VERY_HIGH = "VERY_HIGH"
# Price trend constants (calculated values with 5-level scale)
# Used by trend sensors: momentary, short-term, mid-term, long-term
PRICE_TREND_STRONGLY_FALLING = "strongly_falling"
PRICE_TREND_FALLING = "falling"
PRICE_TREND_STABLE = "stable"
PRICE_TREND_RISING = "rising"
PRICE_TREND_STRONGLY_RISING = "strongly_rising"
# Sensor options (lowercase versions for ENUM device class)
# NOTE: These constants define the valid enum options, but they are not used directly
# in sensor/definitions.py due to import timing issues. Instead, the options are defined inline
@ -491,15 +212,6 @@ VOLATILITY_OPTIONS = [
VOLATILITY_VERY_HIGH.lower(),
]
# Trend options for enum sensors (lowercase versions for ENUM device class)
PRICE_TREND_OPTIONS = [
PRICE_TREND_STRONGLY_FALLING,
PRICE_TREND_FALLING,
PRICE_TREND_STABLE,
PRICE_TREND_RISING,
PRICE_TREND_STRONGLY_RISING,
]
# Valid options for best price maximum level filter
# Sorted from cheap to expensive: user selects "up to how expensive"
BEST_PRICE_MAX_LEVEL_OPTIONS = [
@ -542,16 +254,6 @@ PRICE_RATING_MAPPING = {
PRICE_RATING_HIGH: 1,
}
# Mapping for comparing price trends (used for sorting and automation comparisons)
# Values range from -2 (strongly falling) to +2 (strongly rising), with 0 = stable
PRICE_TREND_MAPPING = {
PRICE_TREND_STRONGLY_FALLING: -2,
PRICE_TREND_FALLING: -1,
PRICE_TREND_STABLE: 0,
PRICE_TREND_RISING: 1,
PRICE_TREND_STRONGLY_RISING: 2,
}
# Icon mapping for price levels (dynamic icons based on level)
PRICE_LEVEL_ICON_MAPPING = {
PRICE_LEVEL_VERY_CHEAP: "mdi:gauge-empty",
@ -650,6 +352,8 @@ BINARY_SENSOR_COLOR_MAPPING = {
},
}
LOGGER = logging.getLogger(__package__)
# Path to custom translations directory
CUSTOM_TRANSLATIONS_DIR = Path(__file__).parent / "custom_translations"

View file

@ -22,12 +22,10 @@ from .constants import (
TIME_SENSITIVE_ENTITY_KEYS,
)
from .core import TibberPricesDataUpdateCoordinator
from .time_service import TibberPricesTimeService
__all__ = [
"MINUTE_UPDATE_ENTITY_KEYS",
"STORAGE_VERSION",
"TIME_SENSITIVE_ENTITY_KEYS",
"TibberPricesDataUpdateCoordinator",
"TibberPricesTimeService",
]

View file

@ -1,48 +1,26 @@
"""
Cache management for coordinator persistent storage.
This module handles persistent storage for the coordinator, storing:
- user_data: Account/home metadata (required, refreshed daily)
- Timestamps for cache validation and lifecycle tracking
**Storage Architecture (as of v0.25.0):**
There are TWO persistent storage files per config entry:
1. `tibber_prices.{entry_id}` (this module)
- user_data: Account info, home metadata, timezone, currency
- Timestamps: last_user_update, last_midnight_check
2. `tibber_prices.interval_pool.{entry_id}` (interval_pool/storage.py)
- Intervals: Deduplicated quarter-hourly price data (source of truth)
- Fetch metadata: When each interval was fetched
- Protected range: Which intervals to keep during cleanup
**Single Source of Truth:**
Price intervals are ONLY stored in IntervalPool. This cache stores only
user metadata and timestamps. The IntervalPool handles all price data
fetching, caching, and persistence independently.
"""
"""Cache management for coordinator module."""
from __future__ import annotations
import logging
from typing import TYPE_CHECKING, Any, NamedTuple
from homeassistant.util import dt as dt_util
if TYPE_CHECKING:
from datetime import datetime
from homeassistant.helpers.storage import Store
from .time_service import TibberPricesTimeService
_LOGGER = logging.getLogger(__name__)
class TibberPricesCacheData(NamedTuple):
"""Cache data structure for user metadata (price data is in IntervalPool)."""
class CacheData(NamedTuple):
"""Cache data structure."""
price_data: dict[str, Any] | None
user_data: dict[str, Any] | None
last_price_update: datetime | None
last_user_update: datetime | None
last_midnight_check: datetime | None
@ -50,27 +28,31 @@ class TibberPricesCacheData(NamedTuple):
async def load_cache(
store: Store,
log_prefix: str,
*,
time: TibberPricesTimeService,
) -> TibberPricesCacheData:
"""Load cached user data from storage (price data is in IntervalPool)."""
) -> CacheData:
"""Load cached data from storage."""
try:
stored = await store.async_load()
if stored:
cached_price_data = stored.get("price_data")
cached_user_data = stored.get("user_data")
# Restore timestamps
last_price_update = None
last_user_update = None
last_midnight_check = None
if last_price_update_str := stored.get("last_price_update"):
last_price_update = dt_util.parse_datetime(last_price_update_str)
if last_user_update_str := stored.get("last_user_update"):
last_user_update = time.parse_datetime(last_user_update_str)
last_user_update = dt_util.parse_datetime(last_user_update_str)
if last_midnight_check_str := stored.get("last_midnight_check"):
last_midnight_check = time.parse_datetime(last_midnight_check_str)
last_midnight_check = dt_util.parse_datetime(last_midnight_check_str)
_LOGGER.debug("%s Cache loaded successfully", log_prefix)
return TibberPricesCacheData(
return CacheData(
price_data=cached_price_data,
user_data=cached_user_data,
last_price_update=last_price_update,
last_user_update=last_user_update,
last_midnight_check=last_midnight_check,
)
@ -79,21 +61,25 @@ async def load_cache(
except OSError as ex:
_LOGGER.warning("%s Failed to load cache: %s", log_prefix, ex)
return TibberPricesCacheData(
return CacheData(
price_data=None,
user_data=None,
last_price_update=None,
last_user_update=None,
last_midnight_check=None,
)
async def save_cache(
async def store_cache(
store: Store,
cache_data: TibberPricesCacheData,
cache_data: CacheData,
log_prefix: str,
) -> None:
"""Store cache data (user metadata only, price data is in IntervalPool)."""
"""Store cache data."""
data = {
"price_data": cache_data.price_data,
"user_data": cache_data.user_data,
"last_price_update": (cache_data.last_price_update.isoformat() if cache_data.last_price_update else None),
"last_user_update": (cache_data.last_user_update.isoformat() if cache_data.last_user_update else None),
"last_midnight_check": (cache_data.last_midnight_check.isoformat() if cache_data.last_midnight_check else None),
}
@ -103,3 +89,34 @@ async def save_cache(
_LOGGER.debug("%s Cache stored successfully", log_prefix)
except OSError:
_LOGGER.exception("%s Failed to store cache", log_prefix)
def is_cache_valid(
cache_data: CacheData,
log_prefix: str,
) -> bool:
"""
Validate if cached price data is still current.
Returns False if:
- No cached data exists
- Cached data is from a different calendar day (in local timezone)
- Midnight turnover has occurred since cache was saved
"""
if cache_data.price_data is None or cache_data.last_price_update is None:
return False
current_local_date = dt_util.as_local(dt_util.now()).date()
last_update_local_date = dt_util.as_local(cache_data.last_price_update).date()
if current_local_date != last_update_local_date:
_LOGGER.debug(
"%s Cache date mismatch: cached=%s, current=%s",
log_prefix,
last_update_local_date,
current_local_date,
)
return False
return True

View file

@ -31,7 +31,6 @@ TIME_SENSITIVE_ENTITY_KEYS = frozenset(
{
# Current/next/previous price sensors
"current_interval_price",
"current_interval_price_base",
"next_interval_price",
"previous_interval_price",
# Current/next/previous price levels
@ -85,12 +84,6 @@ TIME_SENSITIVE_ENTITY_KEYS = frozenset(
"best_price_next_start_time",
"peak_price_end_time",
"peak_price_next_start_time",
# Lifecycle sensor needs quarter-hour precision for state transitions:
# - 23:45: turnover_pending (last interval before midnight)
# - 00:00: turnover complete (after midnight API update)
# - 13:00: searching_tomorrow (when tomorrow data search begins)
# Uses state-change filter in _handle_time_sensitive_update() to prevent recorder spam
"data_lifecycle_status",
}
)

File diff suppressed because it is too large Load diff

View file

@ -0,0 +1,286 @@
"""Data fetching logic for the coordinator."""
from __future__ import annotations
import asyncio
import logging
import secrets
from datetime import timedelta
from typing import TYPE_CHECKING, Any
from custom_components.tibber_prices.api import (
TibberPricesApiClientAuthenticationError,
TibberPricesApiClientCommunicationError,
TibberPricesApiClientError,
)
from homeassistant.core import callback
from homeassistant.exceptions import ConfigEntryAuthFailed
from homeassistant.helpers.update_coordinator import UpdateFailed
from homeassistant.util import dt as dt_util
from . import cache, helpers
from .constants import TOMORROW_DATA_CHECK_HOUR, TOMORROW_DATA_RANDOM_DELAY_MAX
if TYPE_CHECKING:
from collections.abc import Callable
from datetime import date, datetime
from custom_components.tibber_prices.api import TibberPricesApiClient
_LOGGER = logging.getLogger(__name__)
class DataFetcher:
"""Handles data fetching, caching, and main/subentry coordination."""
def __init__(
self,
api: TibberPricesApiClient,
store: Any,
log_prefix: str,
user_update_interval: timedelta,
) -> None:
"""Initialize the data fetcher."""
self.api = api
self._store = store
self._log_prefix = log_prefix
self._user_update_interval = user_update_interval
# Cached data
self._cached_price_data: dict[str, Any] | None = None
self._cached_user_data: dict[str, Any] | None = None
self._last_price_update: datetime | None = None
self._last_user_update: datetime | None = None
def _log(self, level: str, message: str, *args: object, **kwargs: object) -> None:
"""Log with coordinator-specific prefix."""
prefixed_message = f"{self._log_prefix} {message}"
getattr(_LOGGER, level)(prefixed_message, *args, **kwargs)
async def load_cache(self) -> None:
"""Load cached data from storage."""
cache_data = await cache.load_cache(self._store, self._log_prefix)
self._cached_price_data = cache_data.price_data
self._cached_user_data = cache_data.user_data
self._last_price_update = cache_data.last_price_update
self._last_user_update = cache_data.last_user_update
# Validate cache: check if price data is from a previous day
if not cache.is_cache_valid(cache_data, self._log_prefix):
self._log("info", "Cached price data is from a previous day, clearing cache to fetch fresh data")
self._cached_price_data = None
self._last_price_update = None
await self.store_cache()
async def store_cache(self, last_midnight_check: datetime | None = None) -> None:
"""Store cache data."""
cache_data = cache.CacheData(
price_data=self._cached_price_data,
user_data=self._cached_user_data,
last_price_update=self._last_price_update,
last_user_update=self._last_user_update,
last_midnight_check=last_midnight_check,
)
await cache.store_cache(self._store, cache_data, self._log_prefix)
async def update_user_data_if_needed(self, current_time: datetime) -> None:
"""Update user data if needed (daily check)."""
if self._last_user_update is None or current_time - self._last_user_update >= self._user_update_interval:
try:
self._log("debug", "Updating user data")
user_data = await self.api.async_get_viewer_details()
self._cached_user_data = user_data
self._last_user_update = current_time
self._log("debug", "User data updated successfully")
except (
TibberPricesApiClientError,
TibberPricesApiClientCommunicationError,
) as ex:
self._log("warning", "Failed to update user data: %s", ex)
@callback
def should_update_price_data(self, current_time: datetime) -> bool | str:
"""
Check if price data should be updated from the API.
API calls only happen when truly needed:
1. No cached data exists
2. Cache is invalid (from previous day - detected by _is_cache_valid)
3. After 13:00 local time and tomorrow's data is missing or invalid
Cache validity is ensured by:
- _is_cache_valid() checks date mismatch on load
- Midnight turnover clears cache (Timer #2)
- Tomorrow data validation after 13:00
No periodic "safety" updates - trust the cache validation!
Returns:
bool or str: True for immediate update, "tomorrow_check" for tomorrow
data check (needs random delay), False for no update
"""
if self._cached_price_data is None:
self._log("debug", "API update needed: No cached price data")
return True
if self._last_price_update is None:
self._log("debug", "API update needed: No last price update timestamp")
return True
now_local = dt_util.as_local(current_time)
tomorrow_date = (now_local + timedelta(days=1)).date()
# Check if after 13:00 and tomorrow data is missing or invalid
if (
now_local.hour >= TOMORROW_DATA_CHECK_HOUR
and self._cached_price_data
and "homes" in self._cached_price_data
and self.needs_tomorrow_data(tomorrow_date)
):
self._log(
"debug",
"API update needed: After %s:00 and tomorrow's data missing/invalid",
TOMORROW_DATA_CHECK_HOUR,
)
# Return special marker to indicate this is a tomorrow data check
# Caller should add random delay to spread load
return "tomorrow_check"
# No update needed - cache is valid and complete
return False
def needs_tomorrow_data(self, tomorrow_date: date) -> bool:
"""Check if tomorrow data is missing or invalid."""
return helpers.needs_tomorrow_data(self._cached_price_data, tomorrow_date)
async def fetch_all_homes_data(self, configured_home_ids: set[str]) -> dict[str, Any]:
"""Fetch data for all homes (main coordinator only)."""
if not configured_home_ids:
self._log("warning", "No configured homes found - cannot fetch price data")
return {
"timestamp": dt_util.utcnow(),
"homes": {},
}
# Get price data for configured homes only (API call with specific home_ids)
self._log("debug", "Fetching price data for %d configured home(s)", len(configured_home_ids))
price_data = await self.api.async_get_price_info(home_ids=configured_home_ids)
all_homes_data = {}
homes_list = price_data.get("homes", {})
# Process returned data
for home_id, home_price_data in homes_list.items():
# Store raw price data without enrichment
# Enrichment will be done dynamically when data is transformed
home_data = {
"price_info": home_price_data,
}
all_homes_data[home_id] = home_data
self._log(
"debug",
"Successfully fetched data for %d home(s)",
len(all_homes_data),
)
return {
"timestamp": dt_util.utcnow(),
"homes": all_homes_data,
}
async def handle_main_entry_update(
self,
current_time: datetime,
configured_home_ids: set[str],
transform_fn: Callable[[dict[str, Any]], dict[str, Any]],
) -> dict[str, Any]:
"""Handle update for main entry - fetch data for all homes."""
# Update user data if needed (daily check)
await self.update_user_data_if_needed(current_time)
# Check if we need to update price data
should_update = self.should_update_price_data(current_time)
if should_update:
# If this is a tomorrow data check, add random delay to spread API load
if should_update == "tomorrow_check":
# Use secrets for better randomness distribution
delay = secrets.randbelow(TOMORROW_DATA_RANDOM_DELAY_MAX + 1)
self._log(
"debug",
"Tomorrow data check - adding random delay of %d seconds to spread load",
delay,
)
await asyncio.sleep(delay)
self._log("debug", "Fetching fresh price data from API")
raw_data = await self.fetch_all_homes_data(configured_home_ids)
# Cache the data
self._cached_price_data = raw_data
self._last_price_update = current_time
await self.store_cache()
# Transform for main entry: provide aggregated view
return transform_fn(raw_data)
# Use cached data if available
if self._cached_price_data is not None:
self._log("debug", "Using cached price data (no API call needed)")
return transform_fn(self._cached_price_data)
# Fallback: no cache and no update needed (shouldn't happen)
self._log("warning", "No cached data available and update not triggered - returning empty data")
return {
"timestamp": current_time,
"homes": {},
"priceInfo": {},
}
async def handle_api_error(
self,
error: Exception,
transform_fn: Callable[[dict[str, Any]], dict[str, Any]],
) -> dict[str, Any]:
"""Handle API errors with fallback to cached data."""
if isinstance(error, TibberPricesApiClientAuthenticationError):
msg = "Invalid access token"
raise ConfigEntryAuthFailed(msg) from error
# Use cached data as fallback if available
if self._cached_price_data is not None:
self._log("warning", "API error, using cached data: %s", error)
return transform_fn(self._cached_price_data)
msg = f"Error communicating with API: {error}"
raise UpdateFailed(msg) from error
def perform_midnight_turnover(self, price_info: dict[str, Any]) -> dict[str, Any]:
"""
Perform midnight turnover on price data.
Moves: today yesterday, tomorrow today, clears tomorrow.
Args:
price_info: The price info dict with 'today', 'tomorrow', 'yesterday' keys
Returns:
Updated price_info with rotated day data
"""
return helpers.perform_midnight_turnover(price_info)
@property
def cached_price_data(self) -> dict[str, Any] | None:
"""Get cached price data."""
return self._cached_price_data
@cached_price_data.setter
def cached_price_data(self, value: dict[str, Any] | None) -> None:
"""Set cached price data."""
self._cached_price_data = value
@property
def cached_user_data(self) -> dict[str, Any] | None:
"""Get cached user data."""
return self._cached_user_data

View file

@ -2,12 +2,12 @@
from __future__ import annotations
import copy
import logging
from typing import TYPE_CHECKING, Any
from custom_components.tibber_prices import const as _const
from custom_components.tibber_prices.utils.price import enrich_price_info_with_differences
from homeassistant.util import dt as dt_util
if TYPE_CHECKING:
from collections.abc import Callable
@ -15,32 +15,27 @@ if TYPE_CHECKING:
from homeassistant.config_entries import ConfigEntry
from .time_service import TibberPricesTimeService
_LOGGER = logging.getLogger(__name__)
class TibberPricesDataTransformer:
class DataTransformer:
"""Handles data transformation, enrichment, and period calculations."""
def __init__(
self,
config_entry: ConfigEntry,
log_prefix: str,
calculate_periods_fn: Callable[[dict[str, Any]], dict[str, Any]],
time: TibberPricesTimeService,
perform_turnover_fn: Callable[[dict[str, Any]], dict[str, Any]],
) -> None:
"""Initialize the data transformer."""
self.config_entry = config_entry
self._log_prefix = log_prefix
self._calculate_periods_fn = calculate_periods_fn
self.time: TibberPricesTimeService = time
self._perform_turnover_fn = perform_turnover_fn
# Transformation cache
self._cached_transformed_data: dict[str, Any] | None = None
self._last_transformation_config: dict[str, Any] | None = None
self._last_midnight_check: datetime | None = None
self._last_source_data_timestamp: datetime | None = None # Track when source data changed
self._config_cache: dict[str, Any] | None = None
self._config_cache_valid = False
@ -49,50 +44,19 @@ class TibberPricesDataTransformer:
prefixed_message = f"{self._log_prefix} {message}"
getattr(_LOGGER, level)(prefixed_message, *args, **kwargs)
def get_threshold_percentages(self) -> dict[str, int | float]:
"""
Get threshold percentages, hysteresis and gap tolerance for RATING_LEVEL from config options.
CRITICAL: This function is ONLY for rating_level (internal calculation: LOW/NORMAL/HIGH).
Do NOT use for price level (Tibber API: VERY_CHEAP/CHEAP/NORMAL/EXPENSIVE/VERY_EXPENSIVE).
"""
def get_threshold_percentages(self) -> dict[str, int]:
"""Get threshold percentages from config options."""
options = self.config_entry.options or {}
return {
"low": options.get(_const.CONF_PRICE_RATING_THRESHOLD_LOW, _const.DEFAULT_PRICE_RATING_THRESHOLD_LOW),
"high": options.get(_const.CONF_PRICE_RATING_THRESHOLD_HIGH, _const.DEFAULT_PRICE_RATING_THRESHOLD_HIGH),
"hysteresis": options.get(_const.CONF_PRICE_RATING_HYSTERESIS, _const.DEFAULT_PRICE_RATING_HYSTERESIS),
"gap_tolerance": options.get(
_const.CONF_PRICE_RATING_GAP_TOLERANCE, _const.DEFAULT_PRICE_RATING_GAP_TOLERANCE
),
}
def get_level_gap_tolerance(self) -> int:
"""
Get gap tolerance for PRICE LEVEL (Tibber API) from config options.
CRITICAL: This is separate from rating_level gap tolerance.
Price level comes from Tibber API (VERY_CHEAP/CHEAP/NORMAL/EXPENSIVE/VERY_EXPENSIVE).
Rating level is calculated internally (LOW/NORMAL/HIGH).
"""
options = self.config_entry.options or {}
return options.get(_const.CONF_PRICE_LEVEL_GAP_TOLERANCE, _const.DEFAULT_PRICE_LEVEL_GAP_TOLERANCE)
def invalidate_config_cache(self) -> None:
"""
Invalidate config cache AND transformation cache when options change.
CRITICAL: When options like gap_tolerance, hysteresis, or price_level_gap_tolerance
change, we must clear BOTH caches:
1. Config cache (_config_cache) - forces config rebuild on next check
2. Transformation cache (_cached_transformed_data) - forces data re-enrichment
This ensures that the next call to transform_data() will re-calculate
rating_levels and apply new gap tolerance settings to existing price data.
"""
"""Invalidate config cache when options change."""
self._config_cache_valid = False
self._config_cache = None
self._cached_transformed_data = None # Force re-transformation with new config
self._last_transformation_config = None # Force config comparison to trigger
self._log("debug", "Config cache invalidated")
def _get_current_transformation_config(self) -> dict[str, Any]:
"""
@ -105,53 +69,38 @@ class TibberPricesDataTransformer:
return self._config_cache
# Build config dictionary (expensive operation)
options = self.config_entry.options
# Best/peak price remain nested (multi-section steps)
best_period_section = options.get("period_settings", {})
best_flex_section = options.get("flexibility_settings", {})
best_relax_section = options.get("relaxation_and_target_periods", {})
peak_period_section = options.get("period_settings", {})
peak_flex_section = options.get("flexibility_settings", {})
peak_relax_section = options.get("relaxation_and_target_periods", {})
config = {
"thresholds": self.get_threshold_percentages(),
"level_gap_tolerance": self.get_level_gap_tolerance(), # Separate: Tibber's price level smoothing
# Volatility thresholds now flat (single-section step)
"volatility_thresholds": {
"moderate": options.get(_const.CONF_VOLATILITY_THRESHOLD_MODERATE, 15.0),
"high": options.get(_const.CONF_VOLATILITY_THRESHOLD_HIGH, 25.0),
"very_high": options.get(_const.CONF_VOLATILITY_THRESHOLD_VERY_HIGH, 40.0),
},
# Price trend thresholds now flat (single-section step)
"price_trend_thresholds": {
"rising": options.get(
_const.CONF_PRICE_TREND_THRESHOLD_RISING, _const.DEFAULT_PRICE_TREND_THRESHOLD_RISING
),
"falling": options.get(
_const.CONF_PRICE_TREND_THRESHOLD_FALLING, _const.DEFAULT_PRICE_TREND_THRESHOLD_FALLING
),
"moderate": self.config_entry.options.get(_const.CONF_VOLATILITY_THRESHOLD_MODERATE, 15.0),
"high": self.config_entry.options.get(_const.CONF_VOLATILITY_THRESHOLD_HIGH, 25.0),
"very_high": self.config_entry.options.get(_const.CONF_VOLATILITY_THRESHOLD_VERY_HIGH, 40.0),
},
"best_price_config": {
"flex": best_flex_section.get(_const.CONF_BEST_PRICE_FLEX, 15.0),
"max_level": best_period_section.get(_const.CONF_BEST_PRICE_MAX_LEVEL, "NORMAL"),
"min_period_length": best_period_section.get(_const.CONF_BEST_PRICE_MIN_PERIOD_LENGTH, 4),
"min_distance_from_avg": best_flex_section.get(_const.CONF_BEST_PRICE_MIN_DISTANCE_FROM_AVG, -5.0),
"max_level_gap_count": best_period_section.get(_const.CONF_BEST_PRICE_MAX_LEVEL_GAP_COUNT, 0),
"enable_min_periods": best_relax_section.get(_const.CONF_ENABLE_MIN_PERIODS_BEST, False),
"min_periods": best_relax_section.get(_const.CONF_MIN_PERIODS_BEST, 2),
"relaxation_attempts": best_relax_section.get(_const.CONF_RELAXATION_ATTEMPTS_BEST, 4),
"flex": self.config_entry.options.get(_const.CONF_BEST_PRICE_FLEX, 15.0),
"max_level": self.config_entry.options.get(_const.CONF_BEST_PRICE_MAX_LEVEL, "NORMAL"),
"min_period_length": self.config_entry.options.get(_const.CONF_BEST_PRICE_MIN_PERIOD_LENGTH, 4),
"min_distance_from_avg": self.config_entry.options.get(
_const.CONF_BEST_PRICE_MIN_DISTANCE_FROM_AVG, -5.0
),
"max_level_gap_count": self.config_entry.options.get(_const.CONF_BEST_PRICE_MAX_LEVEL_GAP_COUNT, 0),
"enable_min_periods": self.config_entry.options.get(_const.CONF_ENABLE_MIN_PERIODS_BEST, False),
"min_periods": self.config_entry.options.get(_const.CONF_MIN_PERIODS_BEST, 2),
"relaxation_step": self.config_entry.options.get(_const.CONF_RELAXATION_STEP_BEST, 5.0),
"relaxation_attempts": self.config_entry.options.get(_const.CONF_RELAXATION_ATTEMPTS_BEST, 4),
},
"peak_price_config": {
"flex": peak_flex_section.get(_const.CONF_PEAK_PRICE_FLEX, 15.0),
"min_level": peak_period_section.get(_const.CONF_PEAK_PRICE_MIN_LEVEL, "HIGH"),
"min_period_length": peak_period_section.get(_const.CONF_PEAK_PRICE_MIN_PERIOD_LENGTH, 4),
"min_distance_from_avg": peak_flex_section.get(_const.CONF_PEAK_PRICE_MIN_DISTANCE_FROM_AVG, 5.0),
"max_level_gap_count": peak_period_section.get(_const.CONF_PEAK_PRICE_MAX_LEVEL_GAP_COUNT, 0),
"enable_min_periods": peak_relax_section.get(_const.CONF_ENABLE_MIN_PERIODS_PEAK, False),
"min_periods": peak_relax_section.get(_const.CONF_MIN_PERIODS_PEAK, 2),
"relaxation_attempts": peak_relax_section.get(_const.CONF_RELAXATION_ATTEMPTS_PEAK, 4),
"flex": self.config_entry.options.get(_const.CONF_PEAK_PRICE_FLEX, 15.0),
"min_level": self.config_entry.options.get(_const.CONF_PEAK_PRICE_MIN_LEVEL, "HIGH"),
"min_period_length": self.config_entry.options.get(_const.CONF_PEAK_PRICE_MIN_PERIOD_LENGTH, 4),
"min_distance_from_avg": self.config_entry.options.get(
_const.CONF_PEAK_PRICE_MIN_DISTANCE_FROM_AVG, 5.0
),
"max_level_gap_count": self.config_entry.options.get(_const.CONF_PEAK_PRICE_MAX_LEVEL_GAP_COUNT, 0),
"enable_min_periods": self.config_entry.options.get(_const.CONF_ENABLE_MIN_PERIODS_PEAK, False),
"min_periods": self.config_entry.options.get(_const.CONF_MIN_PERIODS_PEAK, 2),
"relaxation_step": self.config_entry.options.get(_const.CONF_RELAXATION_STEP_PEAK, 5.0),
"relaxation_attempts": self.config_entry.options.get(_const.CONF_RELAXATION_ATTEMPTS_PEAK, 4),
},
}
@ -160,43 +109,26 @@ class TibberPricesDataTransformer:
self._config_cache_valid = True
return config
def _should_retransform_data(self, current_time: datetime, source_data_timestamp: datetime | None = None) -> bool:
"""
Check if data transformation should be performed.
Args:
current_time: Current time for midnight check
source_data_timestamp: Timestamp of source data (if available)
Returns:
True if retransformation needed, False if cached data can be used
"""
def _should_retransform_data(self, current_time: datetime) -> bool:
"""Check if data transformation should be performed."""
# No cached transformed data - must transform
if self._cached_transformed_data is None:
return True
# Source data changed - must retransform
# This detects when new API data was fetched (e.g., tomorrow data arrival)
if source_data_timestamp is not None and source_data_timestamp != self._last_source_data_timestamp:
self._log("debug", "Source data changed, retransforming data")
return True
# Configuration changed - must retransform
current_config = self._get_current_transformation_config()
config_changed = current_config != self._last_transformation_config
if config_changed:
if current_config != self._last_transformation_config:
self._log("debug", "Configuration changed, retransforming data")
return True
# Check for midnight turnover
now_local = self.time.as_local(current_time)
now_local = dt_util.as_local(current_time)
current_date = now_local.date()
if self._last_midnight_check is None:
return True
last_check_local = self.time.as_local(self._last_midnight_check)
last_check_local = dt_util.as_local(self._last_midnight_check)
last_check_date = last_check_local.date()
if current_date != last_check_date:
@ -205,80 +137,120 @@ class TibberPricesDataTransformer:
return False
def transform_data(self, raw_data: dict[str, Any]) -> dict[str, Any]:
"""Transform raw data for main entry (single home view)."""
current_time = self.time.now()
source_data_timestamp = raw_data.get("timestamp")
def transform_data_for_main_entry(self, raw_data: dict[str, Any]) -> dict[str, Any]:
"""Transform raw data for main entry (aggregated view of all homes)."""
current_time = dt_util.now()
# Return cached transformed data if no retransformation needed
should_retransform = self._should_retransform_data(current_time, source_data_timestamp)
has_cache = self._cached_transformed_data is not None
self._log(
"info",
"transform_data: should_retransform=%s, has_cache=%s",
should_retransform,
has_cache,
)
if not should_retransform and has_cache:
if not self._should_retransform_data(current_time) and self._cached_transformed_data is not None:
self._log("debug", "Using cached transformed data (no transformation needed)")
# has_cache ensures _cached_transformed_data is not None
return self._cached_transformed_data # type: ignore[return-value]
return self._cached_transformed_data
self._log("debug", "Transforming price data (enrichment + period calculation)")
self._log("debug", "Transforming price data (enrichment only, periods cached separately)")
# Extract data from single-home structure
home_id = raw_data.get("home_id", "")
# CRITICAL: Make a deep copy of intervals to avoid modifying cached raw data
# The enrichment function modifies intervals in-place, which would corrupt
# the original API data and make re-enrichment with different settings impossible
all_intervals = copy.deepcopy(raw_data.get("price_info", []))
currency = raw_data.get("currency", "EUR")
if not all_intervals:
# For main entry, we can show data from the first home as default
# or provide an aggregated view
homes_data = raw_data.get("homes", {})
if not homes_data:
return {
"timestamp": raw_data.get("timestamp"),
"home_id": home_id,
"priceInfo": [],
"pricePeriods": {
"best_price": [],
"peak_price": [],
},
"currency": currency,
"homes": {},
"priceInfo": {},
}
# Enrich price info dynamically with calculated differences and rating levels
# (Modifies all_intervals in-place, returns same list)
thresholds = self.get_threshold_percentages() # Only for rating_level
level_gap_tolerance = self.get_level_gap_tolerance() # Separate: for Tibber's price level
# Use the first home's data as the main entry's data
first_home_data = next(iter(homes_data.values()))
price_info = first_home_data.get("price_info", {})
enriched_intervals = enrich_price_info_with_differences(
all_intervals,
# Perform midnight turnover if needed (handles day transitions)
price_info = self._perform_turnover_fn(price_info)
# Ensure all required keys exist (API might not return tomorrow data yet)
price_info.setdefault("yesterday", [])
price_info.setdefault("today", [])
price_info.setdefault("tomorrow", [])
price_info.setdefault("currency", "EUR")
# Enrich price info dynamically with calculated differences and rating levels
# This ensures enrichment is always up-to-date, especially after midnight turnover
thresholds = self.get_threshold_percentages()
price_info = enrich_price_info_with_differences(
price_info,
threshold_low=thresholds["low"],
threshold_high=thresholds["high"],
hysteresis=float(thresholds["hysteresis"]),
gap_tolerance=int(thresholds["gap_tolerance"]),
level_gap_tolerance=level_gap_tolerance,
time=self.time,
)
# Store enriched intervals directly as priceInfo (flat list)
transformed_data = {
"home_id": home_id,
"priceInfo": enriched_intervals,
"currency": currency,
}
# Note: Periods are calculated and cached separately by PeriodCalculator
# to avoid redundant caching (periods were cached twice before)
# Calculate periods (best price and peak price)
if "priceInfo" in transformed_data:
transformed_data["pricePeriods"] = self._calculate_periods_fn(transformed_data["priceInfo"])
transformed_data = {
"timestamp": raw_data.get("timestamp"),
"homes": homes_data,
"priceInfo": price_info,
}
# Cache the transformed data
self._cached_transformed_data = transformed_data
self._last_transformation_config = self._get_current_transformation_config()
self._last_midnight_check = current_time
return transformed_data
def transform_data_for_subentry(self, main_data: dict[str, Any], home_id: str) -> dict[str, Any]:
"""Transform main coordinator data for subentry (home-specific view)."""
current_time = dt_util.now()
# Return cached transformed data if no retransformation needed
if not self._should_retransform_data(current_time) and self._cached_transformed_data is not None:
self._log("debug", "Using cached transformed data (no transformation needed)")
return self._cached_transformed_data
self._log("debug", "Transforming price data for home (enrichment only, periods cached separately)")
if not home_id:
return main_data
homes_data = main_data.get("homes", {})
home_data = homes_data.get(home_id, {})
if not home_data:
return {
"timestamp": main_data.get("timestamp"),
"priceInfo": {},
}
price_info = home_data.get("price_info", {})
# Perform midnight turnover if needed (handles day transitions)
price_info = self._perform_turnover_fn(price_info)
# Ensure all required keys exist (API might not return tomorrow data yet)
price_info.setdefault("yesterday", [])
price_info.setdefault("today", [])
price_info.setdefault("tomorrow", [])
price_info.setdefault("currency", "EUR")
# Enrich price info dynamically with calculated differences and rating levels
# This ensures enrichment is always up-to-date, especially after midnight turnover
thresholds = self.get_threshold_percentages()
price_info = enrich_price_info_with_differences(
price_info,
threshold_low=thresholds["low"],
threshold_high=thresholds["high"],
)
# Note: Periods are calculated and cached separately by PeriodCalculator
# to avoid redundant caching (periods were cached twice before)
transformed_data = {
"timestamp": main_data.get("timestamp"),
"priceInfo": price_info,
}
# Cache the transformed data
self._cached_transformed_data = transformed_data
self._last_transformation_config = self._get_current_transformation_config()
self._last_midnight_check = current_time
self._last_source_data_timestamp = source_data_timestamp
return transformed_data

View file

@ -2,174 +2,94 @@
from __future__ import annotations
import logging
from datetime import timedelta
from typing import TYPE_CHECKING, Any
from homeassistant.util import dt as dt_util
if TYPE_CHECKING:
from .time_service import TibberPricesTimeService
from datetime import date
_LOGGER = logging.getLogger(__name__)
from homeassistant.core import HomeAssistant
from custom_components.tibber_prices.const import DOMAIN
def get_intervals_for_day_offsets(
coordinator_data: dict[str, Any] | None,
offsets: list[int],
) -> list[dict[str, Any]]:
"""
Get intervals for specific day offsets from coordinator data.
def get_configured_home_ids(hass: HomeAssistant) -> set[str]:
"""Get all home_ids that have active config entries (main + subentries)."""
home_ids = set()
This is the core function for filtering intervals by date offset.
Abstracts the data structure - callers don't need to know where intervals are stored.
# Collect home_ids from all config entries for this domain
for entry in hass.config_entries.async_entries(DOMAIN):
if home_id := entry.data.get("home_id"):
home_ids.add(home_id)
Performance optimized:
- Date comparison using .date() on datetime objects (fast)
- Single pass through intervals with date caching
- Only processes requested offsets
Args:
coordinator_data: Coordinator data dict (typically coordinator.data).
offsets: List of day offsets relative to today (e.g., [0, 1] for today and tomorrow).
Range: -374 to +1 (allows historical comparisons up to one year + one week).
0 = today, -1 = yesterday, +1 = tomorrow, -7 = one week ago, etc.
Returns:
List of intervals matching the requested day offsets, in chronological order.
Example:
# Get only today's intervals
today_intervals = get_intervals_for_day_offsets(coordinator.data, [0])
# Get today and tomorrow
future_intervals = get_intervals_for_day_offsets(coordinator.data, [0, 1])
# Get all available intervals
all = get_intervals_for_day_offsets(coordinator.data, [-1, 0, 1])
# Compare last week with same week one year ago
comparison = get_intervals_for_day_offsets(coordinator.data, [-7, -371])
"""
if not coordinator_data:
return []
# Validate offsets are within acceptable range
min_offset = -374 # One year + one week for comparisons
max_offset = 1 # Tomorrow (we don't have data further in the future)
# Extract intervals from coordinator data structure (priceInfo is now a list)
all_intervals = coordinator_data.get("priceInfo", [])
if not all_intervals:
return []
# Get current local date for comparison (no TimeService needed - use dt_util directly)
now_local = dt_util.now()
today_date = now_local.date()
# Build set of target dates based on requested offsets
target_dates = set()
for offset in offsets:
# Silently clamp offsets to valid range (don't fail on invalid input)
if offset < min_offset or offset > max_offset:
continue
target_date = today_date + timedelta(days=offset)
target_dates.add(target_date)
if not target_dates:
return []
# Filter intervals matching target dates
# Optimized: single pass, date() called once per interval
result = []
for interval in all_intervals:
starts_at = interval.get("startsAt")
if not starts_at:
continue
# Handle both datetime objects and strings (for flexibility)
if isinstance(starts_at, str):
# Parse if string (should be rare after parse_all_timestamps)
starts_at = dt_util.parse_datetime(starts_at)
if not starts_at:
continue
starts_at = dt_util.as_local(starts_at)
# Fast date comparison using datetime.date()
interval_date = starts_at.date()
if interval_date in target_dates:
result.append(interval)
return result
return home_ids
def needs_tomorrow_data(
cached_price_data: dict[str, Any] | None,
) -> bool:
"""
Check if tomorrow data is missing or invalid in cached price data.
Expects single-home cache format: {"price_info": [...], "home_id": "xxx"}
Old multi-home format (v0.14.0) is automatically invalidated by is_cache_valid()
in cache.py, so we only need to handle the current format here.
Uses get_intervals_for_day_offsets() to automatically determine tomorrow
based on current date. No explicit date parameter needed.
Args:
cached_price_data: Cached price data in single-home structure
Returns:
True if tomorrow's data is missing, False otherwise
"""
if not cached_price_data or "price_info" not in cached_price_data:
def needs_tomorrow_data(cached_price_data: dict[str, Any] | None, tomorrow_date: date) -> bool:
"""Check if tomorrow data is missing or invalid."""
if not cached_price_data or "homes" not in cached_price_data:
return False
# Single-home format: {"price_info": [...], "home_id": "xxx"}
# Use helper to get tomorrow's intervals (offset +1 from current date)
coordinator_data = {"priceInfo": cached_price_data.get("price_info", [])}
tomorrow_intervals = get_intervals_for_day_offsets(coordinator_data, [1])
for home_data in cached_price_data["homes"].values():
price_info = home_data.get("price_info", {})
tomorrow_prices = price_info.get("tomorrow", [])
# If no intervals for tomorrow found, we need tomorrow data
return len(tomorrow_intervals) == 0
# Check if tomorrow data is missing
if not tomorrow_prices:
return True
# Check if tomorrow data is actually for tomorrow (validate date)
first_price = tomorrow_prices[0]
if starts_at := first_price.get("startsAt"):
price_time = dt_util.parse_datetime(starts_at)
if price_time:
price_date = dt_util.as_local(price_time).date()
if price_date != tomorrow_date:
return True
return False
def parse_all_timestamps(price_data: dict[str, Any], *, time: TibberPricesTimeService) -> dict[str, Any]:
def perform_midnight_turnover(price_info: dict[str, Any]) -> dict[str, Any]:
"""
Parse all API timestamp strings to datetime objects.
Perform midnight turnover on price data.
This is the SINGLE place where we convert API strings to datetime objects.
After this, all code works with datetime objects, not strings.
Moves: today yesterday, tomorrow today, clears tomorrow.
Performance: ~200 timestamps parsed ONCE instead of multiple times per update cycle.
This handles cases where:
- Server was running through midnight
- Cache is being refreshed and needs proper day rotation
Args:
price_data: Raw API data with string timestamps (single-home structure)
time: TibberPricesTimeService for parsing
price_info: The price info dict with 'today', 'tomorrow', 'yesterday' keys
Returns:
Same structure but with datetime objects instead of strings
Updated price_info with rotated day data
"""
if not price_data:
return price_data
current_local_date = dt_util.as_local(dt_util.now()).date()
# Single-home structure: price_info is a flat list of intervals
price_info = price_data.get("price_info", [])
# Extract current data
today_prices = price_info.get("today", [])
tomorrow_prices = price_info.get("tomorrow", [])
# Skip if price_info is not a list (empty or invalid)
if not isinstance(price_info, list):
return price_data
# Check if any of today's prices are from the previous day
prices_need_rotation = False
if today_prices:
first_today_price_str = today_prices[0].get("startsAt")
if first_today_price_str:
first_today_price_time = dt_util.parse_datetime(first_today_price_str)
if first_today_price_time:
first_today_price_date = dt_util.as_local(first_today_price_time).date()
prices_need_rotation = first_today_price_date < current_local_date
# Parse timestamps in flat interval list
for interval in price_info:
if (starts_at_str := interval.get("startsAt")) and isinstance(starts_at_str, str):
# Parse once, convert to local timezone, store as datetime object
interval["startsAt"] = time.parse_and_localize(starts_at_str)
# If already datetime (e.g., from cache), skip parsing
if prices_need_rotation:
return {
"yesterday": today_prices,
"today": tomorrow_prices,
"tomorrow": [],
"currency": price_info.get("currency", "EUR"),
}
return price_data
return price_info

View file

@ -11,20 +11,14 @@ from homeassistant.helpers.event import async_track_utc_time_change
from .constants import QUARTER_HOUR_BOUNDARIES
if TYPE_CHECKING:
from collections.abc import Callable
from datetime import datetime
from homeassistant.core import HomeAssistant
from .time_service import TibberPricesTimeService
# Callback type that accepts TibberPricesTimeService parameter
TimeServiceCallback = Callable[[TibberPricesTimeService], None]
_LOGGER = logging.getLogger(__name__)
class TibberPricesListenerManager:
class ListenerManager:
"""Manages listeners and scheduling for coordinator updates."""
def __init__(self, hass: HomeAssistant, log_prefix: str) -> None:
@ -33,8 +27,8 @@ class TibberPricesListenerManager:
self._log_prefix = log_prefix
# Listener lists
self._time_sensitive_listeners: list[TimeServiceCallback] = []
self._minute_update_listeners: list[TimeServiceCallback] = []
self._time_sensitive_listeners: list[CALLBACK_TYPE] = []
self._minute_update_listeners: list[CALLBACK_TYPE] = []
# Timer cancellation callbacks
self._quarter_hour_timer_cancel: CALLBACK_TYPE | None = None
@ -49,7 +43,7 @@ class TibberPricesListenerManager:
getattr(_LOGGER, level)(prefixed_message, *args, **kwargs)
@callback
def async_add_time_sensitive_listener(self, update_callback: TimeServiceCallback) -> CALLBACK_TYPE:
def async_add_time_sensitive_listener(self, update_callback: CALLBACK_TYPE) -> CALLBACK_TYPE:
"""
Listen for time-sensitive updates that occur every quarter-hour.
@ -70,16 +64,10 @@ class TibberPricesListenerManager:
return remove_listener
@callback
def async_update_time_sensitive_listeners(self, time_service: TibberPricesTimeService) -> None:
"""
Update all time-sensitive entities without triggering a full coordinator update.
Args:
time_service: TibberPricesTimeService instance with reference time for this update cycle
"""
def async_update_time_sensitive_listeners(self) -> None:
"""Update all time-sensitive entities without triggering a full coordinator update."""
for update_callback in self._time_sensitive_listeners:
update_callback(time_service)
update_callback()
self._log(
"debug",
@ -88,7 +76,7 @@ class TibberPricesListenerManager:
)
@callback
def async_add_minute_update_listener(self, update_callback: TimeServiceCallback) -> CALLBACK_TYPE:
def async_add_minute_update_listener(self, update_callback: CALLBACK_TYPE) -> CALLBACK_TYPE:
"""
Listen for minute-by-minute updates for timing sensors.
@ -109,26 +97,20 @@ class TibberPricesListenerManager:
return remove_listener
@callback
def async_update_minute_listeners(self, time_service: TibberPricesTimeService) -> None:
"""
Update all minute-update entities without triggering a full coordinator update.
Args:
time_service: TibberPricesTimeService instance with reference time for this update cycle
"""
def async_update_minute_listeners(self) -> None:
"""Update all minute-update entities without triggering a full coordinator update."""
for update_callback in self._minute_update_listeners:
update_callback(time_service)
update_callback()
self._log(
"debug",
"Updated %d timing entities (30-second update)",
"Updated %d minute-update entities",
len(self._minute_update_listeners),
)
def schedule_quarter_hour_refresh(
self,
handler_callback: Callable[[datetime], None],
handler_callback: CALLBACK_TYPE,
) -> None:
"""Schedule the next quarter-hour entity refresh using Home Assistant's time tracking."""
# Cancel any existing timer
@ -155,37 +137,27 @@ class TibberPricesListenerManager:
def schedule_minute_refresh(
self,
handler_callback: Callable[[datetime], None],
handler_callback: CALLBACK_TYPE,
) -> None:
"""
Schedule 30-second entity refresh for timing sensors (Timer #3).
This is Timer #3 in the integration's timer architecture. It MUST trigger
at exact 30-second boundaries (0, 30 seconds) to keep timing sensors
(countdown, time-to) accurate.
Home Assistant may introduce small scheduling delays (jitter), which are
corrected using _BOUNDARY_TOLERANCE_SECONDS in time_service.py.
Runs independently of Timer #1 (API polling), which operates at random offsets.
"""
"""Schedule minute-by-minute entity refresh for timing sensors."""
# Cancel any existing timer
if self._minute_timer_cancel:
self._minute_timer_cancel()
self._minute_timer_cancel = None
# Trigger every 30 seconds (:00 and :30) to keep sensor values in sync with
# Home Assistant's frontend relative time display ("in X minutes").
# The timing calculator uses rounded minute values that match HA's rounding behavior.
# Use Home Assistant's async_track_utc_time_change to trigger every minute
# HA may schedule us a few milliseconds before/after the exact minute boundary.
# Our timing calculations are based on dt_util.now() which gives the actual current time,
# so small scheduling variations don't affect accuracy.
self._minute_timer_cancel = async_track_utc_time_change(
self.hass,
handler_callback,
second=[0, 30], # Trigger at :XX:00 and :XX:30
second=0, # Trigger at :XX:00 (HA handles scheduling tolerance)
)
self._log(
"debug",
"Scheduled 30-second refresh for timing sensors (second=[0, 30])",
"Scheduled minute-by-minute refresh for timing sensors (second=0)",
)
def check_midnight_crossed(self, now: datetime) -> bool:

View file

@ -1,121 +0,0 @@
"""
Midnight turnover detection and coordination handler.
This module provides atomic coordination logic for midnight turnover between
multiple timers (DataUpdateCoordinator and quarter-hour refresh timer).
The handler ensures that midnight turnover happens exactly once per day,
regardless of which timer detects it first.
"""
from __future__ import annotations
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from datetime import datetime
class TibberPricesMidnightHandler:
"""
Handles midnight turnover detection and atomic coordination.
This class encapsulates the logic for detecting when midnight has passed
and ensuring that data rotation happens exactly once per day.
The atomic coordination works without locks by comparing date values:
- Timer #1 and Timer #2 both check if current_date > last_checked_date
- First timer to succeed marks the date as checked
- Second timer sees dates are equal and skips turnover
- Timer #3 doesn't participate in midnight logic (only 30-second timing updates)
HA Restart Handling:
- If HA restarts after midnight, _last_midnight_check is None (fresh handler)
- But _last_actual_turnover is restored from cache with yesterday's date
- is_turnover_needed() detects the date mismatch and returns True
- Missed midnight turnover is caught up on first timer run after restart
Attributes:
_last_midnight_check: Last datetime when midnight turnover was checked
_last_actual_turnover: Last datetime when turnover actually happened
"""
def __init__(self) -> None:
"""Initialize the midnight handler."""
self._last_midnight_check: datetime | None = None
self._last_actual_turnover: datetime | None = None
def is_turnover_needed(self, now: datetime) -> bool:
"""
Check if midnight turnover is needed without side effects.
This is a pure check function - it doesn't modify state. Call
mark_turnover_done() after successfully performing the turnover.
IMPORTANT: If handler is uninitialized (HA restart), this checks if we
need to catch up on midnight turnover that happened while HA was down.
Args:
now: Current datetime to check
Returns:
True if midnight has passed since last check, False otherwise
"""
# First time initialization after HA restart
if self._last_midnight_check is None:
# Check if we need to catch up on missed midnight turnover
# If last_actual_turnover exists, we can determine if midnight was missed
if self._last_actual_turnover is not None:
last_turnover_date = self._last_actual_turnover.date()
current_date = now.date()
# Turnover needed if we're on a different day than last turnover
return current_date > last_turnover_date
# Both None = fresh start, no turnover needed yet
return False
# Extract date components
last_checked_date = self._last_midnight_check.date()
current_date = now.date()
# Midnight crossed if current date is after last checked date
return current_date > last_checked_date
def mark_turnover_done(self, now: datetime) -> None:
"""
Mark that midnight turnover has been completed.
Updates both check timestamp and actual turnover timestamp to prevent
duplicate turnover by another timer.
Args:
now: Current datetime when turnover was completed
"""
self._last_midnight_check = now
self._last_actual_turnover = now
def update_check_time(self, now: datetime) -> None:
"""
Update the last check time without marking turnover as done.
Used for initializing the handler or updating the check timestamp
without triggering turnover logic.
Args:
now: Current datetime to set as last check time
"""
if self._last_midnight_check is None:
self._last_midnight_check = now
@property
def last_turnover_time(self) -> datetime | None:
"""Get the timestamp of the last actual turnover."""
return self._last_actual_turnover
@property
def last_check_time(self) -> datetime | None:
"""Get the timestamp of the last midnight check."""
return self._last_midnight_check

View file

@ -6,7 +6,7 @@ This package splits period calculation logic into focused modules:
- level_filtering: Interval-level filtering logic
- period_building: Period construction from intervals
- period_statistics: Statistics calculation
- period_overlap: Overlap resolution logic
- period_merging: Overlap resolution and merging
- relaxation: Per-day relaxation strategy
- core: Main API orchestration
- outlier_filtering: Price spike detection and smoothing
@ -33,11 +33,12 @@ from .types import (
INDENT_L3,
INDENT_L4,
INDENT_L5,
TibberPricesIntervalCriteria,
TibberPricesPeriodConfig,
TibberPricesPeriodData,
TibberPricesPeriodStatistics,
TibberPricesThresholdConfig,
MINUTES_PER_INTERVAL,
IntervalCriteria,
PeriodConfig,
PeriodData,
PeriodStatistics,
ThresholdConfig,
)
__all__ = [
@ -47,11 +48,12 @@ __all__ = [
"INDENT_L3",
"INDENT_L4",
"INDENT_L5",
"TibberPricesIntervalCriteria",
"TibberPricesPeriodConfig",
"TibberPricesPeriodData",
"TibberPricesPeriodStatistics",
"TibberPricesThresholdConfig",
"MINUTES_PER_INTERVAL",
"IntervalCriteria",
"PeriodConfig",
"PeriodData",
"PeriodStatistics",
"ThresholdConfig",
"calculate_periods",
"calculate_periods_with_relaxation",
"filter_price_outliers",

View file

@ -5,9 +5,7 @@ from __future__ import annotations
from typing import TYPE_CHECKING, Any
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator.time_service import TibberPricesTimeService
from .types import TibberPricesPeriodConfig
from .types import PeriodConfig
from .outlier_filtering import (
filter_price_outliers,
@ -16,27 +14,23 @@ from .period_building import (
add_interval_ends,
build_periods,
calculate_reference_prices,
extend_periods_across_midnight,
filter_periods_by_end_date,
filter_periods_by_min_length,
filter_superseded_periods,
split_intervals_by_day,
)
from .period_merging import (
merge_adjacent_periods_at_midnight,
)
from .period_statistics import (
extract_period_summaries,
)
from .types import TibberPricesThresholdConfig
# Flex limits to prevent degenerate behavior (see docs/development/period-calculation-theory.md)
MAX_SAFE_FLEX = 0.50 # 50% - hard cap: above this, period detection becomes unreliable
MAX_OUTLIER_FLEX = 0.25 # 25% - cap for outlier filtering: above this, spike detection too permissive
from .types import ThresholdConfig
def calculate_periods(
all_prices: list[dict],
*,
config: TibberPricesPeriodConfig,
time: TibberPricesTimeService,
config: PeriodConfig,
) -> dict[str, Any]:
"""
Calculate price periods (best or peak) from price data.
@ -49,15 +43,13 @@ def calculate_periods(
2. Calculate reference prices (min/max per day)
3. Build periods based on criteria
4. Filter by minimum length
5. Add interval ends
6. Filter periods by end date
7. Extract period summaries (start/end times, not full price data)
5. Merge adjacent periods at midnight
6. Extract period summaries (start/end times, not full price data)
Args:
all_prices: All price data points from yesterday/today/tomorrow.
all_prices: All price data points from yesterday/today/tomorrow
config: Period configuration containing reverse_sort, flex, min_distance_from_avg,
min_period_length, threshold_low, and threshold_high.
time: TibberPricesTimeService instance (required).
min_period_length, threshold_low, and threshold_high
Returns:
Dict with:
@ -66,34 +58,14 @@ def calculate_periods(
- reference_data: Daily min/max/avg for on-demand annotation
"""
# Import logger at the start of function
import logging # noqa: PLC0415
from .types import INDENT_L0 # noqa: PLC0415
_LOGGER = logging.getLogger(__name__) # noqa: N806
# Extract config values
reverse_sort = config.reverse_sort
flex_raw = config.flex # Already normalized to positive by get_period_config()
flex = config.flex
min_distance_from_avg = config.min_distance_from_avg
min_period_length = config.min_period_length
threshold_low = config.threshold_low
threshold_high = config.threshold_high
# CRITICAL: Hard cap flex at 50% to prevent degenerate behavior
# Above 50%, period detection becomes unreliable (too many intervals qualify)
# NOTE: flex_raw is already positive from normalization in get_period_config()
flex = flex_raw
if flex_raw > MAX_SAFE_FLEX:
flex = MAX_SAFE_FLEX
_LOGGER.warning(
"Flex %.1f%% exceeds maximum safe value! Capping at %.0f%%. "
"Recommendation: Use 15-20%% with relaxation enabled, or 25-35%% without relaxation.",
flex_raw * 100,
MAX_SAFE_FLEX * 100,
)
if not all_prices:
return {
"periods": [],
@ -116,7 +88,7 @@ def calculate_periods(
all_prices_sorted = sorted(all_prices, key=lambda p: p["startsAt"])
# Step 1: Split by day and calculate averages
intervals_by_day, avg_price_by_day = split_intervals_by_day(all_prices_sorted, time=time)
intervals_by_day, avg_price_by_day = split_intervals_by_day(all_prices_sorted)
# Step 2: Calculate reference prices (min or max per day)
ref_prices = calculate_reference_prices(intervals_by_day, reverse_sort=reverse_sort)
@ -124,27 +96,9 @@ def calculate_periods(
# Step 2.5: Filter price outliers (smoothing for period formation only)
# This runs BEFORE period formation to prevent isolated price spikes
# from breaking up otherwise continuous periods
# CRITICAL: Cap flexibility for outlier filtering at 25%
# High flex (>25%) makes outlier detection too permissive, accepting
# unstable price contexts as "normal". This breaks period formation.
# User's flex setting still applies to period criteria (in_flex check).
# Import details logger locally (core.py imports logger locally in function)
_LOGGER_DETAILS = logging.getLogger(__name__ + ".details") # noqa: N806
outlier_flex = min(abs(flex) * 100, MAX_OUTLIER_FLEX * 100)
if abs(flex) * 100 > MAX_OUTLIER_FLEX * 100:
_LOGGER_DETAILS.debug(
"%sOutlier filtering: Using capped flex %.1f%% (user setting: %.1f%%)",
INDENT_L0,
outlier_flex,
abs(flex) * 100,
)
all_prices_smoothed = filter_price_outliers(
all_prices_sorted,
outlier_flex, # Use capped flex for outlier detection
abs(flex) * 100, # Convert to percentage (e.g., 0.15 → 15.0)
min_period_length,
)
@ -152,7 +106,6 @@ def calculate_periods(
price_context = {
"ref_prices": ref_prices,
"avg_prices": avg_price_by_day,
"intervals_by_day": intervals_by_day, # Needed for day volatility calculation
"flex": flex,
"min_distance_from_avg": min_distance_from_avg,
}
@ -162,38 +115,24 @@ def calculate_periods(
reverse_sort=reverse_sort,
level_filter=config.level_filter,
gap_count=config.gap_count,
time=time,
)
_LOGGER.debug(
"%sAfter build_periods: %d raw periods found (flex=%.1f%%, level_filter=%s)",
INDENT_L0,
len(raw_periods),
abs(flex) * 100,
config.level_filter or "None",
)
# Step 4: Filter by minimum length
raw_periods = filter_periods_by_min_length(raw_periods, min_period_length, time=time)
_LOGGER.debug(
"%sAfter filter_by_min_length (>= %d min): %d periods remain",
INDENT_L0,
min_period_length,
len(raw_periods),
)
raw_periods = filter_periods_by_min_length(raw_periods, min_period_length)
# Step 5: Add interval ends
add_interval_ends(raw_periods, time=time)
# Step 5: Merge adjacent periods at midnight
raw_periods = merge_adjacent_periods_at_midnight(raw_periods)
# Step 6: Filter periods by end date (keep periods ending yesterday or later)
# This ensures coordinator cache contains yesterday/today/tomorrow periods
# Sensors filter further for today+tomorrow, services can access all cached periods
raw_periods = filter_periods_by_end_date(raw_periods, time=time)
# Step 6: Add interval ends
add_interval_ends(raw_periods)
# Step 7: Extract lightweight period summaries (no full price data)
# Note: Periods are filtered by end date to keep yesterday/today/tomorrow.
# This preserves periods that started day-before-yesterday but end yesterday.
thresholds = TibberPricesThresholdConfig(
# Step 7: Filter periods by end date (keep periods ending today or later)
raw_periods = filter_periods_by_end_date(raw_periods)
# Step 8: Extract lightweight period summaries (no full price data)
# Note: Filtering for current/future is done here based on end date,
# not start date. This preserves periods that started yesterday but end today.
thresholds = ThresholdConfig(
threshold_low=threshold_low,
threshold_high=threshold_high,
threshold_volatility_moderate=config.threshold_volatility_moderate,
@ -206,27 +145,6 @@ def calculate_periods(
all_prices_sorted,
price_context,
thresholds,
time=time,
)
# Step 8: Cross-day extension for late-night periods
# If a best-price period ends near midnight and tomorrow has continued low prices,
# extend the period across midnight to give users the full cheap window
period_summaries = extend_periods_across_midnight(
period_summaries,
all_prices_sorted,
price_context,
time=time,
reverse_sort=reverse_sort,
)
# Step 9: Filter superseded periods
# When tomorrow data is available, late-night today periods that were found via
# relaxation may be obsolete if tomorrow has significantly better alternatives
period_summaries = filter_superseded_periods(
period_summaries,
time=time,
reverse_sort=reverse_sort,
)
return {

View file

@ -1,30 +1,14 @@
"""
Interval-level filtering logic for period calculation.
Key Concepts:
- Flex Filter: Limits price distance from daily min/max
- Min Distance Filter: Ensures prices are significantly different from average
- Dynamic Scaling: Min_Distance reduces at high Flex to prevent conflicts
See docs/development/period-calculation-theory.md for detailed explanation.
"""
"""Interval-level filtering logic for period calculation."""
from __future__ import annotations
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from .types import TibberPricesIntervalCriteria
from .types import IntervalCriteria
from custom_components.tibber_prices.const import PRICE_LEVEL_MAPPING
# Module-local log indentation (each module starts at level 0)
INDENT_L0 = "" # Entry point / main function
# Flex threshold for min_distance scaling
FLEX_SCALING_THRESHOLD = 0.20 # 20% - start adjusting min_distance
SCALE_FACTOR_WARNING_THRESHOLD = 0.8 # Log when reduction > 20%
def check_level_with_gap_tolerance(
interval_level: int,
@ -104,16 +88,11 @@ def apply_level_filter(
def check_interval_criteria(
price: float,
criteria: TibberPricesIntervalCriteria,
criteria: IntervalCriteria,
) -> tuple[bool, bool]:
"""
Check if interval meets flex and minimum distance criteria.
CRITICAL: This function works with NORMALIZED values (always positive):
- criteria.flex: Always positive (e.g., 0.20 for 20%)
- criteria.min_distance_from_avg: Always positive (e.g., 5.0 for 5%)
- criteria.reverse_sort: Determines direction (True=Peak, False=Best)
Args:
price: Interval price
criteria: Interval criteria (ref_price, avg_price, flex, etc.)
@ -122,87 +101,20 @@ def check_interval_criteria(
Tuple of (in_flex, meets_min_distance)
"""
# Normalize inputs to absolute values for consistent calculation
flex_abs = abs(criteria.flex)
min_distance_abs = abs(criteria.min_distance_from_avg)
# Calculate percentage difference from reference
percent_diff = ((price - criteria.ref_price) / criteria.ref_price) * 100 if criteria.ref_price != 0 else 0.0
# ============================================================
# FLEX FILTER: Check if price is within flex threshold of reference
# ============================================================
# Reference price is:
# - Peak price (reverse_sort=True): daily MAXIMUM
# - Best price (reverse_sort=False): daily MINIMUM
#
# Flex band calculation (using absolute values):
# - Peak price: [max - max*flex, max] → accept prices near the maximum
# - Best price: [min, min + min*flex] → accept prices near the minimum
#
# Examples with flex=20%:
# - Peak: max=30 ct → accept [24, 30] ct (prices ≥ 24 ct)
# - Best: min=10 ct → accept [10, 12] ct (prices ≤ 12 ct)
# Check if interval qualifies for the period
in_flex = percent_diff >= criteria.flex * 100 if criteria.reverse_sort else percent_diff <= criteria.flex * 100
if criteria.ref_price == 0:
# Zero reference: flex has no effect, use strict equality
in_flex = price == 0
else:
# Calculate flex amount using absolute value
flex_amount = abs(criteria.ref_price) * flex_abs
if criteria.reverse_sort:
# Peak price: accept prices >= (ref_price - flex_amount)
# Prices must be CLOSE TO or AT the maximum
flex_threshold = criteria.ref_price - flex_amount
in_flex = price >= flex_threshold
else:
# Best price: accept prices <= (ref_price + flex_amount)
# Accept ALL low prices up to the flex threshold, not just those >= minimum
# This ensures that if there are multiple low-price intervals, all that meet
# the threshold are included, regardless of whether they're before or after
# the daily minimum in the chronological sequence.
flex_threshold = criteria.ref_price + flex_amount
in_flex = price <= flex_threshold
# ============================================================
# MIN_DISTANCE FILTER: Check if price is far enough from average
# ============================================================
# CRITICAL: Adjust min_distance dynamically based on flex to prevent conflicts
# Problem: High flex (e.g., 50%) can conflict with fixed min_distance (e.g., 5%)
# Solution: When flex is high, reduce min_distance requirement proportionally
adjusted_min_distance = min_distance_abs
if flex_abs > FLEX_SCALING_THRESHOLD:
# Scale down min_distance as flex increases
# At 20% flex: multiplier = 1.0 (full min_distance)
# At 40% flex: multiplier = 0.5 (half min_distance)
# At 50% flex: multiplier = 0.25 (quarter min_distance)
flex_excess = flex_abs - 0.20 # How much above 20%
scale_factor = max(0.25, 1.0 - (flex_excess * 2.5)) # Linear reduction, min 25%
adjusted_min_distance = min_distance_abs * scale_factor
# Log adjustment at DEBUG level (only when significant reduction)
if scale_factor < SCALE_FACTOR_WARNING_THRESHOLD:
import logging # noqa: PLC0415
_LOGGER = logging.getLogger(f"{__name__}.details") # noqa: N806
_LOGGER.debug(
"High flex %.1f%% detected: Reducing min_distance %.1f%%%.1f%% (scale %.2f)",
flex_abs * 100,
min_distance_abs,
adjusted_min_distance,
scale_factor,
)
# Calculate threshold from average (using normalized positive distance)
# - Peak price: threshold = avg * (1 + distance/100) → prices must be ABOVE avg+distance
# - Best price: threshold = avg * (1 - distance/100) → prices must be BELOW avg-distance
# Minimum distance from average
if criteria.reverse_sort:
# Peak: price must be >= avg * (1 + distance%)
min_distance_threshold = criteria.avg_price * (1 + adjusted_min_distance / 100)
# Peak price: must be at least min_distance_from_avg% above average
min_distance_threshold = criteria.avg_price * (1 + criteria.min_distance_from_avg / 100)
meets_min_distance = price >= min_distance_threshold
else:
# Best: price must be <= avg * (1 - distance%)
min_distance_threshold = criteria.avg_price * (1 - adjusted_min_distance / 100)
# Best price: must be at least min_distance_from_avg% below average
min_distance_threshold = criteria.avg_price * (1 - criteria.min_distance_from_avg / 100)
meets_min_distance = price <= min_distance_threshold
return in_flex, meets_min_distance

View file

@ -15,40 +15,25 @@ Uses statistical methods:
from __future__ import annotations
import logging
from datetime import datetime
from typing import NamedTuple
from custom_components.tibber_prices.utils.price import calculate_coefficient_of_variation
from dataclasses import dataclass
_LOGGER = logging.getLogger(__name__)
_LOGGER_DETAILS = logging.getLogger(__name__ + ".details")
# Outlier filtering constants
MIN_CONTEXT_SIZE = 3 # Minimum intervals needed before/after for analysis
CONFIDENCE_LEVEL = 2.0 # Standard deviations for 95% confidence interval
VOLATILITY_THRESHOLD = 0.05 # 5% max relative std dev for zigzag detection
SYMMETRY_THRESHOLD = 1.5 # Max std dev difference for symmetric spike
RELATIVE_VOLATILITY_THRESHOLD = 2.0 # Window volatility vs context (cluster detection)
ASYMMETRY_TAIL_WINDOW = 6 # Skip asymmetry check for last ~1.5h (6 intervals) of available data
ZIGZAG_TAIL_WINDOW = 6 # Skip zigzag/cluster detection for last ~1.5h (6 intervals)
EXTREMES_PROTECTION_TOLERANCE = 0.001 # Protect prices within 0.1% of daily min/max from smoothing
# Adaptive confidence level constants
# Uses coefficient of variation (CV) from utils/price.py for consistency with volatility sensors
# On flat days (low CV), we're more conservative (higher confidence = fewer smoothed)
# On volatile days (high CV), we're more aggressive (lower confidence = more smoothed)
CONFIDENCE_LEVEL_MIN = 1.5 # Minimum confidence (volatile days: smooth more aggressively)
CONFIDENCE_LEVEL_MAX = 2.5 # Maximum confidence (flat days: smooth more conservatively)
CONFIDENCE_LEVEL_DEFAULT = 2.0 # Default: 95% confidence interval (2 std devs)
# CV thresholds for adaptive confidence (align with volatility sensor defaults)
# These are in percentage points (e.g., 10.0 = 10% CV)
DAILY_CV_LOW = 10.0 # ≤10% CV = flat day (use max confidence)
DAILY_CV_HIGH = 30.0 # ≥30% CV = volatile day (use min confidence)
# Module-local log indentation (each module starts at level 0)
INDENT_L0 = "" # All logs in this module (no indentation needed)
class TibberPricesSpikeCandidateContext(NamedTuple):
@dataclass(slots=True)
class SpikeCandidateContext:
"""Container for spike validation parameters."""
current: dict
@ -68,7 +53,7 @@ def _should_skip_tail_check(
) -> bool:
"""Return True when remaining intervals fall inside tail window and log why."""
if remaining_intervals < tail_window:
_LOGGER_DETAILS.debug(
_LOGGER.debug(
"%sSpike at %s: Skipping %s check (only %d intervals remaining)",
INDENT_L0,
interval_label,
@ -198,7 +183,7 @@ def _detect_zigzag_pattern(window: list[dict], context_std_dev: float) -> bool:
def _validate_spike_candidate(
candidate: TibberPricesSpikeCandidateContext,
candidate: SpikeCandidateContext,
) -> bool:
"""Run stability, symmetry, and zigzag checks before smoothing."""
avg_before = sum(x["total"] for x in candidate.context_before) / len(candidate.context_before)
@ -206,7 +191,7 @@ def _validate_spike_candidate(
context_diff_pct = abs(avg_after - avg_before) / avg_before if avg_before > 0 else 0
if context_diff_pct > candidate.flexibility_ratio:
_LOGGER_DETAILS.debug(
_LOGGER.debug(
"%sInterval %s: Context unstable (%.1f%% change) - not a spike",
INDENT_L0,
candidate.current.get("startsAt", "unknown interval"),
@ -220,7 +205,7 @@ def _validate_spike_candidate(
"asymmetry",
candidate.current.get("startsAt", "unknown interval"),
) and not _check_symmetry(avg_before, avg_after, candidate.stats["std_dev"]):
_LOGGER_DETAILS.debug(
_LOGGER.debug(
"%sSpike at %s rejected: Asymmetric (before=%.2f, after=%.2f ct/kWh)",
INDENT_L0,
candidate.current.get("startsAt", "unknown interval"),
@ -238,7 +223,7 @@ def _validate_spike_candidate(
return True
if _detect_zigzag_pattern(candidate.analysis_window, candidate.stats["std_dev"]):
_LOGGER_DETAILS.debug(
_LOGGER.debug(
"%sSpike at %s rejected: Zigzag/cluster pattern detected",
INDENT_L0,
candidate.current.get("startsAt", "unknown interval"),
@ -248,166 +233,6 @@ def _validate_spike_candidate(
return True
def _calculate_daily_extremes(intervals: list[dict]) -> dict[str, tuple[float, float]]:
"""
Calculate daily min/max prices for each day in the interval list.
These extremes are used to protect reference prices from being smoothed.
The daily minimum is the reference for best_price periods, and the daily
maximum is the reference for peak_price periods - smoothing these would
break period detection.
Args:
intervals: List of price intervals with 'startsAt' and 'total' keys
Returns:
Dict mapping date strings to (min_price, max_price) tuples
"""
daily_prices: dict[str, list[float]] = {}
for interval in intervals:
starts_at = interval.get("startsAt")
if starts_at is None:
continue
# Handle both datetime objects and ISO strings
dt = datetime.fromisoformat(starts_at) if isinstance(starts_at, str) else starts_at
date_key = dt.strftime("%Y-%m-%d")
price = float(interval["total"])
daily_prices.setdefault(date_key, []).append(price)
# Calculate min/max for each day
return {date_key: (min(prices), max(prices)) for date_key, prices in daily_prices.items()}
def _calculate_daily_cv(intervals: list[dict]) -> dict[str, float]:
"""
Calculate daily coefficient of variation (CV) for each day.
Uses the same CV calculation as volatility sensors for consistency.
CV = (std_dev / mean) * 100, expressed as percentage.
Used to adapt the confidence level for outlier detection:
- Flat days (low CV): Higher confidence fewer false positives
- Volatile days (high CV): Lower confidence catch more real outliers
Args:
intervals: List of price intervals with 'startsAt' and 'total' keys
Returns:
Dict mapping date strings to CV percentage (e.g., 15.0 for 15% CV)
"""
daily_prices: dict[str, list[float]] = {}
for interval in intervals:
starts_at = interval.get("startsAt")
if starts_at is None:
continue
dt = datetime.fromisoformat(starts_at) if isinstance(starts_at, str) else starts_at
date_key = dt.strftime("%Y-%m-%d")
price = float(interval["total"])
daily_prices.setdefault(date_key, []).append(price)
# Calculate CV using the shared function from utils/price.py
result = {}
for date_key, prices in daily_prices.items():
cv = calculate_coefficient_of_variation(prices)
result[date_key] = cv if cv is not None else 0.0
return result
def _get_adaptive_confidence_level(
interval: dict,
daily_cv: dict[str, float],
) -> float:
"""
Get adaptive confidence level based on daily coefficient of variation (CV).
Maps daily CV to confidence level:
- Low CV (10%): High confidence (2.5) conservative, fewer smoothed
- High CV (30%): Low confidence (1.5) aggressive, more smoothed
- Between: Linear interpolation
Uses the same CV calculation as volatility sensors for consistency.
Args:
interval: Price interval dict with 'startsAt' key
daily_cv: Dict from _calculate_daily_cv()
Returns:
Confidence level multiplier for std_dev threshold
"""
starts_at = interval.get("startsAt")
if starts_at is None:
return CONFIDENCE_LEVEL_DEFAULT
dt = datetime.fromisoformat(starts_at) if isinstance(starts_at, str) else starts_at
date_key = dt.strftime("%Y-%m-%d")
cv = daily_cv.get(date_key, 0.0)
# Linear interpolation between LOW and HIGH CV
# Low CV → high confidence (conservative)
# High CV → low confidence (aggressive)
if cv <= DAILY_CV_LOW:
return CONFIDENCE_LEVEL_MAX
if cv >= DAILY_CV_HIGH:
return CONFIDENCE_LEVEL_MIN
# Linear interpolation: as CV increases, confidence decreases
ratio = (cv - DAILY_CV_LOW) / (DAILY_CV_HIGH - DAILY_CV_LOW)
return CONFIDENCE_LEVEL_MAX - (ratio * (CONFIDENCE_LEVEL_MAX - CONFIDENCE_LEVEL_MIN))
def _is_daily_extreme(
interval: dict,
daily_extremes: dict[str, tuple[float, float]],
tolerance: float = EXTREMES_PROTECTION_TOLERANCE,
) -> bool:
"""
Check if an interval's price is at or very near a daily extreme.
Prices at daily extremes should never be smoothed because:
- Daily minimum is the reference for best_price period detection
- Daily maximum is the reference for peak_price period detection
- Smoothing these would cause periods to miss their most important intervals
Args:
interval: Price interval dict with 'startsAt' and 'total' keys
daily_extremes: Dict from _calculate_daily_extremes()
tolerance: Relative tolerance for matching (default 0.1%)
Returns:
True if the price is at or very near a daily min or max
"""
starts_at = interval.get("startsAt")
if starts_at is None:
return False
# Handle both datetime objects and ISO strings
dt = datetime.fromisoformat(starts_at) if isinstance(starts_at, str) else starts_at
date_key = dt.strftime("%Y-%m-%d")
if date_key not in daily_extremes:
return False
price = float(interval["total"])
daily_min, daily_max = daily_extremes[date_key]
# Check if price is within tolerance of daily min or max
# Using relative tolerance: |price - extreme| <= extreme * tolerance
min_threshold = daily_min * (1 + tolerance)
max_threshold = daily_max * (1 - tolerance)
return price <= min_threshold or price >= max_threshold
def filter_price_outliers(
intervals: list[dict],
flexibility_pct: float,
@ -435,29 +260,15 @@ def filter_price_outliers(
Intervals with smoothed prices (marked with _smoothed flag)
"""
# Convert percentage to ratio once for all comparisons (e.g., 15.0 → 0.15)
flexibility_ratio = flexibility_pct / 100
# Calculate daily extremes to protect reference prices from smoothing
# Daily min is the reference for best_price, daily max for peak_price
daily_extremes = _calculate_daily_extremes(intervals)
# Calculate daily coefficient of variation (CV) for adaptive confidence levels
# Uses same CV calculation as volatility sensors for consistency
# Flat days → conservative smoothing, volatile days → aggressive smoothing
daily_cv = _calculate_daily_cv(intervals)
# Log CV info for debugging (CV is in percentage points, e.g., 15.0 = 15%)
cv_info = ", ".join(f"{date}: {cv:.1f}%" for date, cv in sorted(daily_cv.items()))
_LOGGER.info(
"%sSmoothing price outliers: %d intervals, flex=%.1f%%, daily CV: %s",
"%sSmoothing price outliers: %d intervals, flex=%.1f%%",
INDENT_L0,
len(intervals),
flexibility_pct,
cv_info,
)
protected_count = 0
# Convert percentage to ratio once for all comparisons (e.g., 15.0 → 0.15)
flexibility_ratio = flexibility_pct / 100
result = []
smoothed_count = 0
@ -465,20 +276,6 @@ def filter_price_outliers(
for i, current in enumerate(intervals):
current_price = current["total"]
# CRITICAL: Never smooth daily extremes - they are the reference prices!
# Smoothing the daily min would break best_price period detection,
# smoothing the daily max would break peak_price period detection.
if _is_daily_extreme(current, daily_extremes):
result.append(current)
protected_count += 1
_LOGGER_DETAILS.debug(
"%sProtected daily extreme at %s: %.2f ct/kWh (not smoothed)",
INDENT_L0,
current.get("startsAt", f"index {i}"),
current_price * 100,
)
continue
# Get context windows (3 intervals before and after)
context_before = intervals[max(0, i - MIN_CONTEXT_SIZE) : i]
context_after = intervals[i + 1 : min(len(intervals), i + 1 + MIN_CONTEXT_SIZE)]
@ -500,11 +297,8 @@ def filter_price_outliers(
# Calculate how far current price deviates from expected
residual = abs(current_price - expected_price)
# Adaptive confidence level based on daily CV:
# - Flat days (low CV): higher confidence (2.5) → fewer false positives
# - Volatile days (high CV): lower confidence (1.5) → catch more real spikes
confidence_level = _get_adaptive_confidence_level(current, daily_cv)
tolerance = stats["std_dev"] * confidence_level
# Tolerance based on statistical confidence (2 std dev = 95% confidence)
tolerance = stats["std_dev"] * CONFIDENCE_LEVEL
# Not a spike if within tolerance
if residual <= tolerance:
@ -514,7 +308,7 @@ def filter_price_outliers(
# SPIKE CANDIDATE DETECTED - Now validate
remaining_intervals = len(intervals) - (i + 1)
analysis_window = [*context_before[-2:], current, *context_after[:2]]
candidate_context = TibberPricesSpikeCandidateContext(
candidate_context = SpikeCandidateContext(
current=current,
context_before=context_before,
context_after=context_after,
@ -537,23 +331,24 @@ def filter_price_outliers(
result.append(smoothed)
smoothed_count += 1
_LOGGER_DETAILS.debug(
"%sSmoothed spike at %s: %.2f%.2f ct/kWh (residual: %.2f, tolerance: %.2f, confidence: %.2f)",
_LOGGER.debug(
"%sSmoothed spike at %s: %.2f%.2f ct/kWh (residual: %.2f, tolerance: %.2f, trend_slope: %.4f)",
INDENT_L0,
current.get("startsAt", f"index {i}"),
current_price * 100,
expected_price * 100,
residual * 100,
tolerance * 100,
confidence_level,
stats["trend_slope"] * 100,
)
if smoothed_count > 0 or protected_count > 0:
if smoothed_count > 0:
_LOGGER.info(
"%sPrice outlier smoothing complete: %d smoothed, %d protected (daily extremes)",
"%sPrice outlier smoothing complete: %d/%d intervals smoothed (%.1f%%)",
INDENT_L0,
smoothed_count,
protected_count,
len(intervals),
(smoothed_count / len(intervals)) * 100,
)
return result

View file

@ -3,38 +3,37 @@
from __future__ import annotations
import logging
from datetime import date, datetime, timedelta
from typing import TYPE_CHECKING, Any
from datetime import date, timedelta
from typing import Any
from custom_components.tibber_prices.const import PRICE_LEVEL_MAPPING
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator.time_service import TibberPricesTimeService
from homeassistant.util import dt as dt_util
from .level_filtering import (
apply_level_filter,
check_interval_criteria,
)
from .types import TibberPricesIntervalCriteria
from .types import (
MINUTES_PER_INTERVAL,
IntervalCriteria,
)
_LOGGER = logging.getLogger(__name__)
_LOGGER_DETAILS = logging.getLogger(__name__ + ".details")
# Module-local log indentation (each module starts at level 0)
INDENT_L0 = "" # Entry point / main function
def split_intervals_by_day(
all_prices: list[dict], *, time: TibberPricesTimeService
) -> tuple[dict[date, list[dict]], dict[date, float]]:
def split_intervals_by_day(all_prices: list[dict]) -> tuple[dict[date, list[dict]], dict[date, float]]:
"""Split intervals by day and calculate average price per day."""
intervals_by_day: dict[date, list[dict]] = {}
avg_price_by_day: dict[date, float] = {}
for price_data in all_prices:
dt = time.get_interval_time(price_data)
dt = dt_util.parse_datetime(price_data["startsAt"])
if dt is None:
continue
dt = dt_util.as_local(dt)
date_key = dt.date()
intervals_by_day.setdefault(date_key, []).append(price_data)
@ -53,22 +52,20 @@ def calculate_reference_prices(intervals_by_day: dict[date, list[dict]], *, reve
return ref_prices
def build_periods( # noqa: PLR0913, PLR0915, PLR0912 - Complex period building logic requires many arguments, statements, and branches
def build_periods( # noqa: PLR0915 - Complex period building logic requires many statements
all_prices: list[dict],
price_context: dict[str, Any],
*,
reverse_sort: bool,
level_filter: str | None = None,
gap_count: int = 0,
time: TibberPricesTimeService,
) -> list[list[dict]]:
"""
Build periods, allowing periods to cross midnight (day boundary).
Periods can span multiple days. Each interval is evaluated against the reference
price (min/max) and average price of its own day. This ensures fair filtering
criteria even when periods cross midnight, where prices can jump significantly
due to different forecasting uncertainty (prices at day end vs. day start).
Periods are built day-by-day, comparing each interval to its own day's reference.
When a day boundary is crossed, the current period is ended.
Adjacent periods at midnight are merged in a later step.
Args:
all_prices: All price data points
@ -76,7 +73,6 @@ def build_periods( # noqa: PLR0913, PLR0915, PLR0912 - Complex period building
reverse_sort: True for peak price (high prices), False for best price (low prices)
level_filter: Level filter string ("cheap", "expensive", "any", None)
gap_count: Number of allowed consecutive intervals deviating by exactly 1 level step
time: TibberPricesTimeService instance (required)
"""
ref_prices = price_context["ref_prices"]
@ -92,7 +88,7 @@ def build_periods( # noqa: PLR0913, PLR0915, PLR0912 - Complex period building
level_filter_active = True
filter_direction = "" if reverse_sort else ""
gap_info = f", gap_tolerance={gap_count}" if gap_count > 0 else ""
_LOGGER_DETAILS.debug(
_LOGGER.debug(
"%sLevel filter active: %s (order %s, require interval level %s filter level%s)",
INDENT_L0,
level_filter.upper(),
@ -102,20 +98,20 @@ def build_periods( # noqa: PLR0913, PLR0915, PLR0912 - Complex period building
)
else:
status = "RELAXED to ANY" if (level_filter and level_filter.lower() == "any") else "DISABLED (not configured)"
_LOGGER_DETAILS.debug("%sLevel filter: %s (accepting all levels)", INDENT_L0, status)
_LOGGER.debug("%sLevel filter: %s (accepting all levels)", INDENT_L0, status)
periods: list[list[dict]] = []
current_period: list[dict] = []
last_ref_date: date | None = None
consecutive_gaps = 0 # Track consecutive intervals that deviate by 1 level step
intervals_checked = 0
intervals_filtered_by_level = 0
intervals_filtered_by_flex = 0
intervals_filtered_by_min_distance = 0
for price_data in all_prices:
starts_at = time.get_interval_time(price_data)
starts_at = dt_util.parse_datetime(price_data["startsAt"])
if starts_at is None:
continue
starts_at = dt_util.as_local(starts_at)
date_key = starts_at.date()
# Use smoothed price for criteria checks (flex/distance)
@ -125,29 +121,16 @@ def build_periods( # noqa: PLR0913, PLR0915, PLR0912 - Complex period building
intervals_checked += 1
# CRITICAL: Always use reference price from the interval's own day
# Each interval must meet the criteria of its own day, not the period start day.
# This ensures fair filtering even when periods cross midnight, where prices
# can jump significantly (last intervals of a day have more risk buffer than
# first intervals of next day, as they're set with different uncertainty levels).
ref_date = date_key
# Check flex and minimum distance criteria (using smoothed price and interval's own day reference)
criteria = TibberPricesIntervalCriteria(
ref_price=ref_prices[ref_date],
avg_price=avg_prices[ref_date],
# Check flex and minimum distance criteria (using smoothed price)
criteria = IntervalCriteria(
ref_price=ref_prices[date_key],
avg_price=avg_prices[date_key],
flex=flex,
min_distance_from_avg=min_distance_from_avg,
reverse_sort=reverse_sort,
)
in_flex, meets_min_distance = check_interval_criteria(price_for_criteria, criteria)
# Track why intervals are filtered
if not in_flex:
intervals_filtered_by_flex += 1
if not meets_min_distance:
intervals_filtered_by_min_distance += 1
# If this interval was smoothed, check if smoothing actually made a difference
smoothing_was_impactful = False
if price_data.get("_smoothed", False):
@ -165,6 +148,14 @@ def build_periods( # noqa: PLR0913, PLR0915, PLR0912 - Complex period building
if not meets_level:
intervals_filtered_by_level += 1
# Split period if day changes
if last_ref_date is not None and date_key != last_ref_date and current_period:
periods.append(current_period)
current_period = []
consecutive_gaps = 0 # Reset gap counter on day boundary
last_ref_date = date_key
# Add to period if all criteria are met
if in_flex and meets_min_distance and meets_level:
current_period.append(
@ -189,79 +180,50 @@ def build_periods( # noqa: PLR0913, PLR0915, PLR0912 - Complex period building
if current_period:
periods.append(current_period)
# Log detailed filter statistics
if intervals_checked > 0:
_LOGGER_DETAILS.debug(
"%sFilter statistics: %d intervals checked",
# Log summary
if level_filter_active and intervals_checked > 0:
filtered_pct = (intervals_filtered_by_level / intervals_checked) * 100
_LOGGER.debug(
"%sLevel filter summary: %d/%d intervals filtered (%.1f%%)",
INDENT_L0,
intervals_filtered_by_level,
intervals_checked,
filtered_pct,
)
if intervals_filtered_by_flex > 0:
flex_pct = (intervals_filtered_by_flex / intervals_checked) * 100
_LOGGER_DETAILS.debug(
"%s Filtered by FLEX (price too far from ref): %d/%d (%.1f%%)",
INDENT_L0,
intervals_filtered_by_flex,
intervals_checked,
flex_pct,
)
if intervals_filtered_by_min_distance > 0:
distance_pct = (intervals_filtered_by_min_distance / intervals_checked) * 100
_LOGGER_DETAILS.debug(
"%s Filtered by MIN_DISTANCE (price too close to avg): %d/%d (%.1f%%)",
INDENT_L0,
intervals_filtered_by_min_distance,
intervals_checked,
distance_pct,
)
if level_filter_active and intervals_filtered_by_level > 0:
level_pct = (intervals_filtered_by_level / intervals_checked) * 100
_LOGGER_DETAILS.debug(
"%s Filtered by LEVEL (wrong price level): %d/%d (%.1f%%)",
INDENT_L0,
intervals_filtered_by_level,
intervals_checked,
level_pct,
)
return periods
def filter_periods_by_min_length(
periods: list[list[dict]], min_period_length: int, *, time: TibberPricesTimeService
) -> list[list[dict]]:
def filter_periods_by_min_length(periods: list[list[dict]], min_period_length: int) -> list[list[dict]]:
"""Filter periods to only include those meeting the minimum length requirement."""
min_intervals = time.minutes_to_intervals(min_period_length)
min_intervals = min_period_length // MINUTES_PER_INTERVAL
return [period for period in periods if len(period) >= min_intervals]
def add_interval_ends(periods: list[list[dict]], *, time: TibberPricesTimeService) -> None:
def add_interval_ends(periods: list[list[dict]]) -> None:
"""Add interval_end to each interval in-place."""
interval_duration = time.get_interval_duration()
for period in periods:
for interval in period:
start = interval.get("interval_start")
if start:
interval["interval_end"] = start + interval_duration
interval["interval_end"] = start + timedelta(minutes=MINUTES_PER_INTERVAL)
def filter_periods_by_end_date(periods: list[list[dict]], *, time: TibberPricesTimeService) -> list[list[dict]]:
def filter_periods_by_end_date(periods: list[list[dict]]) -> list[list[dict]]:
"""
Filter periods to keep only relevant ones for yesterday, today, and tomorrow.
Filter periods to keep only relevant ones for today and tomorrow.
Keep periods that:
- End yesterday or later (>= start of yesterday)
- End in the future (> now)
- End today but after the start of the day (not exactly at midnight)
This removes:
- Periods that ended before yesterday (day-before-yesterday or earlier)
Rationale: Coordinator caches periods for yesterday/today/tomorrow so that:
- Binary sensors can filter for today+tomorrow (current/next periods)
- Services can access yesterday's periods when user requests "yesterday" data
- Periods that ended yesterday
- Periods that ended exactly at midnight today (they're completely in the past)
"""
now = time.now()
# Calculate start of yesterday (midnight yesterday)
yesterday_start = time.start_of_local_day(now) - time.get_interval_duration() * 96 # 96 intervals = 24 hours
now = dt_util.now()
today = now.date()
midnight_today = dt_util.start_of_local_day(now)
filtered = []
for period in periods:
@ -275,433 +237,13 @@ def filter_periods_by_end_date(periods: list[list[dict]], *, time: TibberPricesT
if not period_end:
continue
# Keep if period ends yesterday or later
if period_end >= yesterday_start:
# Keep if period ends in the future
if period_end > now:
filtered.append(period)
continue
# Keep if period ends today but AFTER midnight (not exactly at midnight)
if period_end.date() == today and period_end > midnight_today:
filtered.append(period)
return filtered
def _categorize_periods_for_supersession(
period_summaries: list[dict],
today: date,
tomorrow: date,
late_hour_threshold: int,
early_hour_limit: int,
) -> tuple[list[dict], list[dict], list[dict]]:
"""Categorize periods into today-late, tomorrow-early, and other."""
today_late: list[dict] = []
tomorrow_early: list[dict] = []
other: list[dict] = []
for period in period_summaries:
period_start = period.get("start")
period_end = period.get("end")
if not period_start or not period_end:
other.append(period)
# Today late-night periods: START today at or after late_hour_threshold (e.g., 20:00)
# Note: period_end could be tomorrow (e.g., 23:30-00:00 spans midnight)
elif period_start.date() == today and period_start.hour >= late_hour_threshold:
today_late.append(period)
# Tomorrow early-morning periods: START tomorrow before early_hour_limit (e.g., 08:00)
elif period_start.date() == tomorrow and period_start.hour < early_hour_limit:
tomorrow_early.append(period)
else:
other.append(period)
return today_late, tomorrow_early, other
def _filter_superseded_today_periods(
today_late_periods: list[dict],
best_tomorrow: dict,
best_tomorrow_price: float,
improvement_threshold: float,
) -> list[dict]:
"""Filter today periods that are superseded by a better tomorrow period."""
kept: list[dict] = []
for today_period in today_late_periods:
today_price = today_period.get("price_mean")
if today_price is None:
kept.append(today_period)
continue
# Calculate how much better tomorrow is (as percentage)
improvement_pct = ((today_price - best_tomorrow_price) / today_price * 100) if today_price > 0 else 0
_LOGGER.debug(
"Supersession check: Today %s-%s (%.4f) vs Tomorrow %s-%s (%.4f) = %.1f%% improvement (threshold: %.1f%%)",
today_period["start"].strftime("%H:%M"),
today_period["end"].strftime("%H:%M"),
today_price,
best_tomorrow["start"].strftime("%H:%M"),
best_tomorrow["end"].strftime("%H:%M"),
best_tomorrow_price,
improvement_pct,
improvement_threshold,
)
if improvement_pct >= improvement_threshold:
_LOGGER.info(
"Period superseded: Today %s-%s (%.2f) replaced by Tomorrow %s-%s (%.2f, %.1f%% better)",
today_period["start"].strftime("%H:%M"),
today_period["end"].strftime("%H:%M"),
today_price,
best_tomorrow["start"].strftime("%H:%M"),
best_tomorrow["end"].strftime("%H:%M"),
best_tomorrow_price,
improvement_pct,
)
else:
kept.append(today_period)
return kept
def filter_superseded_periods(
period_summaries: list[dict],
*,
time: TibberPricesTimeService,
reverse_sort: bool,
) -> list[dict]:
"""
Filter out late-night today periods that are superseded by better tomorrow periods.
When tomorrow's data becomes available, some late-night periods that were found
through relaxation may no longer make sense. If tomorrow has a significantly
better period in the early morning, the late-night today period is obsolete.
Example:
- Today 23:30-00:00 at 0.70 kr (found via relaxation, was best available)
- Tomorrow 04:00-05:30 at 0.50 kr (much better alternative)
The today period is superseded and should be filtered out
This only applies to best-price periods (reverse_sort=False).
Peak-price periods are not filtered this way.
"""
from .types import ( # noqa: PLC0415
CROSS_DAY_LATE_PERIOD_START_HOUR,
CROSS_DAY_MAX_EXTENSION_HOUR,
SUPERSESSION_PRICE_IMPROVEMENT_PCT,
)
_LOGGER.debug(
"filter_superseded_periods called: %d periods, reverse_sort=%s",
len(period_summaries) if period_summaries else 0,
reverse_sort,
)
# Only filter for best-price periods
if reverse_sort or not period_summaries:
return period_summaries
now = time.now()
today = now.date()
tomorrow = today + timedelta(days=1)
# Categorize periods
today_late, tomorrow_early, other = _categorize_periods_for_supersession(
period_summaries,
today,
tomorrow,
CROSS_DAY_LATE_PERIOD_START_HOUR,
CROSS_DAY_MAX_EXTENSION_HOUR,
)
_LOGGER.debug(
"Supersession categorization: today_late=%d, tomorrow_early=%d, other=%d",
len(today_late),
len(tomorrow_early),
len(other),
)
# If no tomorrow early periods, nothing to compare against
if not tomorrow_early:
_LOGGER.debug("No tomorrow early periods - skipping supersession check")
return period_summaries
# Find the best tomorrow early period (lowest mean price)
best_tomorrow = min(tomorrow_early, key=lambda p: p.get("price_mean", float("inf")))
best_tomorrow_price = best_tomorrow.get("price_mean")
if best_tomorrow_price is None:
return period_summaries
# Filter superseded today periods
kept_today = _filter_superseded_today_periods(
today_late,
best_tomorrow,
best_tomorrow_price,
SUPERSESSION_PRICE_IMPROVEMENT_PCT,
)
# Reconstruct and sort by start time
result = other + kept_today + tomorrow_early
result.sort(key=lambda p: p.get("start") or time.now())
return result
def _is_period_eligible_for_extension(
period: dict,
today: date,
late_hour_threshold: int,
) -> bool:
"""
Check if a period is eligible for cross-day extension.
Eligibility criteria:
- Period has valid start and end times
- Period ends on today (not yesterday or tomorrow)
- Period ends late (after late_hour_threshold, e.g. 20:00)
"""
period_end = period.get("end")
period_start = period.get("start")
if not period_end or not period_start:
return False
if period_end.date() != today:
return False
return period_end.hour >= late_hour_threshold
def _find_extension_intervals(
period_end: datetime,
price_lookup: dict[str, dict],
criteria: Any,
max_extension_time: datetime,
interval_duration: timedelta,
) -> list[dict]:
"""
Find consecutive intervals after period_end that meet criteria.
Iterates forward from period_end, adding intervals while they
meet the flex and min_distance criteria. Stops at first failure
or when reaching max_extension_time.
"""
from .level_filtering import check_interval_criteria # noqa: PLC0415
extension_intervals: list[dict] = []
check_time = period_end
while check_time < max_extension_time:
price_data = price_lookup.get(check_time.isoformat())
if not price_data:
break # No more data
price = float(price_data["total"])
in_flex, meets_min_distance = check_interval_criteria(price, criteria)
if not (in_flex and meets_min_distance):
break # Criteria no longer met
extension_intervals.append(price_data)
check_time = check_time + interval_duration
return extension_intervals
def _collect_original_period_prices(
period_start: datetime,
period_end: datetime,
price_lookup: dict[str, dict],
interval_duration: timedelta,
) -> list[float]:
"""Collect prices from original period for CV calculation."""
prices: list[float] = []
current = period_start
while current < period_end:
price_data = price_lookup.get(current.isoformat())
if price_data:
prices.append(float(price_data["total"]))
current = current + interval_duration
return prices
def _build_extended_period(
period: dict,
extension_intervals: list[dict],
combined_prices: list[float],
combined_cv: float,
interval_duration: timedelta,
) -> dict:
"""Create extended period dict with updated statistics."""
period_start = period["start"]
period_end = period["end"]
new_end = period_end + (interval_duration * len(extension_intervals))
extended = period.copy()
extended["end"] = new_end
extended["duration_minutes"] = int((new_end - period_start).total_seconds() / 60)
extended["period_interval_count"] = len(combined_prices)
extended["cross_day_extended"] = True
extended["cross_day_extension_intervals"] = len(extension_intervals)
# Recalculate price statistics
extended["price_min"] = min(combined_prices)
extended["price_max"] = max(combined_prices)
extended["price_mean"] = sum(combined_prices) / len(combined_prices)
extended["price_spread"] = extended["price_max"] - extended["price_min"]
extended["price_coefficient_variation_%"] = round(combined_cv, 1)
return extended
def extend_periods_across_midnight(
period_summaries: list[dict],
all_prices: list[dict],
price_context: dict[str, Any],
*,
time: TibberPricesTimeService,
reverse_sort: bool,
) -> list[dict]:
"""
Extend late-night periods across midnight if favorable prices continue.
When a period ends close to midnight and tomorrow's data shows continued
favorable prices, extend the period into the next day. This prevents
artificial period breaks at midnight when it's actually better to continue.
Example: Best price period 22:00-23:45 today could extend to 04:00 tomorrow
if prices remain low overnight.
Rules:
- Only extends periods ending after CROSS_DAY_LATE_PERIOD_START_HOUR (20:00)
- Won't extend beyond CROSS_DAY_MAX_EXTENSION_HOUR (08:00) next day
- Extension must pass same flex criteria as original period
- Quality Gate (CV check) applies to extended period
Args:
period_summaries: List of period summary dicts (already processed)
all_prices: All price intervals including tomorrow
price_context: Dict with ref_prices, avg_prices, flex, min_distance_from_avg
time: Time service instance
reverse_sort: True for peak price, False for best price
Returns:
Updated list of period summaries with extensions applied
"""
from custom_components.tibber_prices.utils.price import calculate_coefficient_of_variation # noqa: PLC0415
from .types import ( # noqa: PLC0415
CROSS_DAY_LATE_PERIOD_START_HOUR,
CROSS_DAY_MAX_EXTENSION_HOUR,
PERIOD_MAX_CV,
TibberPricesIntervalCriteria,
)
if not period_summaries or not all_prices:
return period_summaries
# Build price lookup by timestamp
price_lookup: dict[str, dict] = {}
for price_data in all_prices:
interval_time = time.get_interval_time(price_data)
if interval_time:
price_lookup[interval_time.isoformat()] = price_data
ref_prices = price_context.get("ref_prices", {})
avg_prices = price_context.get("avg_prices", {})
flex = price_context.get("flex", 0.15)
min_distance = price_context.get("min_distance_from_avg", 0)
now = time.now()
today = now.date()
tomorrow = today + timedelta(days=1)
interval_duration = time.get_interval_duration()
# Max extension time (e.g., 08:00 tomorrow)
max_extension_time = time.start_of_local_day(now) + timedelta(days=1, hours=CROSS_DAY_MAX_EXTENSION_HOUR)
extended_summaries = []
for period in period_summaries:
# Check eligibility for extension
if not _is_period_eligible_for_extension(period, today, CROSS_DAY_LATE_PERIOD_START_HOUR):
extended_summaries.append(period)
continue
# Get tomorrow's reference prices
tomorrow_ref = ref_prices.get(tomorrow) or ref_prices.get(str(tomorrow))
tomorrow_avg = avg_prices.get(tomorrow) or avg_prices.get(str(tomorrow))
if tomorrow_ref is None or tomorrow_avg is None:
extended_summaries.append(period)
continue
# Set up criteria for extension check
criteria = TibberPricesIntervalCriteria(
ref_price=tomorrow_ref,
avg_price=tomorrow_avg,
flex=flex,
min_distance_from_avg=min_distance,
reverse_sort=reverse_sort,
)
# Find extension intervals
extension_intervals = _find_extension_intervals(
period["end"],
price_lookup,
criteria,
max_extension_time,
interval_duration,
)
if not extension_intervals:
extended_summaries.append(period)
continue
# Collect all prices for CV check
original_prices = _collect_original_period_prices(
period["start"],
period["end"],
price_lookup,
interval_duration,
)
extension_prices = [float(p["total"]) for p in extension_intervals]
combined_prices = original_prices + extension_prices
# Quality Gate: Check CV of extended period
combined_cv = calculate_coefficient_of_variation(combined_prices)
if combined_cv is not None and combined_cv <= PERIOD_MAX_CV:
# Extension passes quality gate
extended_period = _build_extended_period(
period,
extension_intervals,
combined_prices,
combined_cv,
interval_duration,
)
_LOGGER.info(
"Cross-day extension: Period %s-%s extended to %s (+%d intervals, CV=%.1f%%)",
period["start"].strftime("%H:%M"),
period["end"].strftime("%H:%M"),
extended_period["end"].strftime("%H:%M"),
len(extension_intervals),
combined_cv,
)
extended_summaries.append(extended_period)
else:
# Extension would exceed quality gate
_LOGGER_DETAILS.debug(
"%sCross-day extension rejected for period %s-%s: CV=%.1f%% > %.1f%%",
INDENT_L0,
period["start"].strftime("%H:%M"),
period["end"].strftime("%H:%M"),
combined_cv or 0,
PERIOD_MAX_CV,
)
extended_summaries.append(period)
return extended_summaries

View file

@ -0,0 +1,383 @@
"""Period merging and overlap resolution logic."""
from __future__ import annotations
import logging
from datetime import datetime, timedelta
from homeassistant.util import dt as dt_util
from .types import MINUTES_PER_INTERVAL
_LOGGER = logging.getLogger(__name__)
# Module-local log indentation (each module starts at level 0)
INDENT_L0 = "" # Entry point / main function
INDENT_L1 = " " # Nested logic / loop iterations
INDENT_L2 = " " # Deeper nesting
def merge_adjacent_periods_at_midnight(periods: list[list[dict]]) -> list[list[dict]]:
"""
Merge adjacent periods that meet at midnight.
When two periods are detected separately for consecutive days but are directly
adjacent at midnight (15 minutes apart), merge them into a single period.
"""
if not periods:
return periods
merged = []
i = 0
while i < len(periods):
current_period = periods[i]
# Check if there's a next period and if they meet at midnight
if i + 1 < len(periods):
next_period = periods[i + 1]
last_start = current_period[-1].get("interval_start")
next_start = next_period[0].get("interval_start")
if last_start and next_start:
time_diff = next_start - last_start
last_date = last_start.date()
next_date = next_start.date()
# If they are 15 minutes apart and on different days (crossing midnight)
if time_diff == timedelta(minutes=MINUTES_PER_INTERVAL) and next_date > last_date:
# Merge the two periods
merged_period = current_period + next_period
merged.append(merged_period)
i += 2 # Skip both periods as we've merged them
continue
# If no merge happened, just add the current period
merged.append(current_period)
i += 1
return merged
def recalculate_period_metadata(periods: list[dict]) -> None:
"""
Recalculate period metadata after merging periods.
Updates period_position, periods_total, and periods_remaining for all periods
based on chronological order.
This must be called after resolve_period_overlaps() to ensure metadata
reflects the final merged period list.
Args:
periods: List of period summary dicts (mutated in-place)
"""
if not periods:
return
# Sort periods chronologically by start time
periods.sort(key=lambda p: p.get("start") or dt_util.now())
# Update metadata for all periods
total_periods = len(periods)
for position, period in enumerate(periods, 1):
period["period_position"] = position
period["periods_total"] = total_periods
period["periods_remaining"] = total_periods - position
def split_period_by_overlaps(
period_start: datetime,
period_end: datetime,
overlaps: list[tuple[datetime, datetime]],
) -> list[tuple[datetime, datetime]]:
"""
Split a time period into segments that don't overlap with given ranges.
Args:
period_start: Start of period to split
period_end: End of period to split
overlaps: List of (start, end) tuples representing overlapping ranges
Returns:
List of (start, end) tuples for non-overlapping segments
Example:
period: 09:00-15:00
overlaps: [(10:00-12:00), (14:00-16:00)]
result: [(09:00-10:00), (12:00-14:00)]
"""
# Sort overlaps by start time
sorted_overlaps = sorted(overlaps, key=lambda x: x[0])
segments = []
current_pos = period_start
for overlap_start, overlap_end in sorted_overlaps:
# Add segment before this overlap (if any)
if current_pos < overlap_start:
segments.append((current_pos, overlap_start))
# Move position past this overlap
current_pos = max(current_pos, overlap_end)
# Add final segment after all overlaps (if any)
if current_pos < period_end:
segments.append((current_pos, period_end))
return segments
def resolve_period_overlaps( # noqa: PLR0912, PLR0915, C901 - Complex overlap resolution with replacement and extension logic
existing_periods: list[dict],
new_relaxed_periods: list[dict],
min_period_length: int,
baseline_periods: list[dict] | None = None,
) -> tuple[list[dict], int]:
"""
Resolve overlaps between existing periods and newly found relaxed periods.
Existing periods (baseline + previous relaxation phases) have priority and remain unchanged.
Newly relaxed periods are adjusted to not overlap with existing periods.
After splitting relaxed periods to avoid overlaps, each segment is validated against
min_period_length. Segments shorter than this threshold are discarded.
This function is called incrementally after each relaxation phase:
- Phase 1: existing = accumulated, baseline = baseline
- Phase 2: existing = accumulated, baseline = baseline
- Phase 3: existing = accumulated, baseline = baseline
Args:
existing_periods: All previously found periods (baseline + earlier relaxation phases)
new_relaxed_periods: Periods found in current relaxation phase (will be adjusted)
min_period_length: Minimum period length in minutes (segments shorter than this are discarded)
baseline_periods: Original baseline periods (for extension detection). Extensions only count
against baseline, not against other relaxation periods.
Returns:
Tuple of (merged_periods, count_standalone_relaxed):
- merged_periods: All periods (existing + adjusted new), sorted by start time
- count_standalone_relaxed: Number of new relaxed periods that count toward min_periods
(excludes extensions of baseline periods only)
"""
if baseline_periods is None:
baseline_periods = existing_periods # Fallback to existing if not provided
_LOGGER.debug(
"%sresolve_period_overlaps called: existing=%d, new=%d, baseline=%d",
INDENT_L0,
len(existing_periods),
len(new_relaxed_periods),
len(baseline_periods),
)
if not new_relaxed_periods:
return existing_periods.copy(), 0
if not existing_periods:
# No overlaps possible - all relaxed periods are standalone
return new_relaxed_periods.copy(), len(new_relaxed_periods)
merged = existing_periods.copy()
count_standalone = 0
for relaxed in new_relaxed_periods:
# Skip if this exact period is already in existing_periods (duplicate from previous relaxation attempt)
# Compare current start/end (before any splitting), not original_start/end
# Note: original_start/end are set AFTER splitting and indicate split segments from same source
relaxed_start = relaxed["start"]
relaxed_end = relaxed["end"]
is_duplicate = False
for existing in existing_periods:
# Only compare with existing periods that haven't been adjusted (unsplit originals)
# If existing has original_start/end, it's already a split segment - skip comparison
if "original_start" in existing:
continue
existing_start = existing["start"]
existing_end = existing["end"]
# Duplicate if same boundaries (within 1 minute tolerance)
tolerance_seconds = 60 # 1 minute tolerance for duplicate detection
if (
abs((relaxed_start - existing_start).total_seconds()) < tolerance_seconds
and abs((relaxed_end - existing_end).total_seconds()) < tolerance_seconds
):
is_duplicate = True
_LOGGER.debug(
"%sSkipping duplicate period %s-%s (already exists from previous relaxation)",
INDENT_L1,
relaxed_start.strftime("%H:%M"),
relaxed_end.strftime("%H:%M"),
)
break
if is_duplicate:
continue
# Find all overlapping existing periods
overlaps = []
for existing in existing_periods:
existing_start = existing["start"]
existing_end = existing["end"]
# Check for overlap
if relaxed_start < existing_end and relaxed_end > existing_start:
overlaps.append((existing_start, existing_end))
if not overlaps:
# No overlap - check if adjacent to baseline period (= extension)
# Only baseline extensions don't count toward min_periods
is_extension = False
for baseline in baseline_periods:
if relaxed_end == baseline["start"] or relaxed_start == baseline["end"]:
is_extension = True
break
if is_extension:
relaxed["is_extension"] = True
_LOGGER.debug(
"%sMarking period %s-%s as extension (no overlap, adjacent to baseline)",
INDENT_L1,
relaxed_start.strftime("%H:%M"),
relaxed_end.strftime("%H:%M"),
)
else:
count_standalone += 1
merged.append(relaxed)
else:
# Has overlaps - check if this new period extends BASELINE periods
# Extension = new period encompasses/extends baseline period(s)
# Note: If new period encompasses OTHER RELAXED periods, that's a replacement, not extension!
is_extension = False
periods_to_replace = []
for existing in existing_periods:
existing_start = existing["start"]
existing_end = existing["end"]
# Check if new period completely encompasses existing period
if relaxed_start <= existing_start and relaxed_end >= existing_end:
# Is this existing period a BASELINE period?
is_baseline = any(
bp["start"] == existing_start and bp["end"] == existing_end for bp in baseline_periods
)
if is_baseline:
# Extension of baseline → counts as extension
is_extension = True
_LOGGER.debug(
"%sNew period %s-%s extends BASELINE period %s-%s",
INDENT_L1,
relaxed_start.strftime("%H:%M"),
relaxed_end.strftime("%H:%M"),
existing_start.strftime("%H:%M"),
existing_end.strftime("%H:%M"),
)
else:
# Encompasses another relaxed period → REPLACEMENT, not extension
periods_to_replace.append(existing)
_LOGGER.debug(
"%sNew period %s-%s replaces relaxed period %s-%s (larger is better)",
INDENT_L1,
relaxed_start.strftime("%H:%M"),
relaxed_end.strftime("%H:%M"),
existing_start.strftime("%H:%M"),
existing_end.strftime("%H:%M"),
)
# Remove periods that are being replaced by this larger period
if periods_to_replace:
for period_to_remove in periods_to_replace:
if period_to_remove in merged:
merged.remove(period_to_remove)
_LOGGER.debug(
"%sReplaced period %s-%s with larger period %s-%s",
INDENT_L2,
period_to_remove["start"].strftime("%H:%M"),
period_to_remove["end"].strftime("%H:%M"),
relaxed_start.strftime("%H:%M"),
relaxed_end.strftime("%H:%M"),
)
# Split the relaxed period into non-overlapping segments
segments = split_period_by_overlaps(relaxed_start, relaxed_end, overlaps)
# If no segments (completely overlapped), but we replaced periods, add the full period
if not segments and periods_to_replace:
_LOGGER.debug(
"%sAdding full replacement period %s-%s (no non-overlapping segments)",
INDENT_L2,
relaxed_start.strftime("%H:%M"),
relaxed_end.strftime("%H:%M"),
)
# Mark as extension if it extends baseline, otherwise standalone
if is_extension:
relaxed["is_extension"] = True
merged.append(relaxed)
continue
for seg_start, seg_end in segments:
# Calculate segment duration in minutes
segment_duration_minutes = int((seg_end - seg_start).total_seconds() / 60)
# Skip segment if it's too short
if segment_duration_minutes < min_period_length:
continue
# Create adjusted period segment
adjusted_period = relaxed.copy()
adjusted_period["start"] = seg_start
adjusted_period["end"] = seg_end
adjusted_period["duration_minutes"] = segment_duration_minutes
# Mark as adjusted and potentially as extension
adjusted_period["adjusted_for_overlap"] = True
adjusted_period["original_start"] = relaxed_start
adjusted_period["original_end"] = relaxed_end
# If the original period was an extension, all its segments are extensions too
# OR if segment is adjacent to baseline
segment_is_extension = is_extension
if not segment_is_extension:
# Check if segment is directly adjacent to BASELINE period
for baseline in baseline_periods:
if seg_end == baseline["start"] or seg_start == baseline["end"]:
segment_is_extension = True
break
if segment_is_extension:
adjusted_period["is_extension"] = True
_LOGGER.debug(
"%sMarking segment %s-%s as extension (original was extension or adjacent to baseline)",
INDENT_L2,
seg_start.strftime("%H:%M"),
seg_end.strftime("%H:%M"),
)
else:
# Standalone segment counts toward min_periods
count_standalone += 1
merged.append(adjusted_period)
# Sort all periods by start time
merged.sort(key=lambda p: p["start"])
# Count ACTUAL standalone periods in final merged list (not just newly added ones)
# This accounts for replacements where old standalone was replaced by new standalone
final_standalone_count = len([p for p in merged if not p.get("is_extension")])
# Subtract baseline standalone count to get NEW standalone from this relaxation
baseline_standalone_count = len([p for p in baseline_periods if not p.get("is_extension")])
new_standalone_count = final_standalone_count - baseline_standalone_count
return merged, new_standalone_count

View file

@ -1,380 +0,0 @@
"""Period overlap resolution logic."""
from __future__ import annotations
import logging
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator.time_service import TibberPricesTimeService
_LOGGER = logging.getLogger(__name__)
_LOGGER_DETAILS = logging.getLogger(__name__ + ".details")
# Module-local log indentation (each module starts at level 0)
INDENT_L0 = "" # Entry point / main function
INDENT_L1 = " " # Nested logic / loop iterations
INDENT_L2 = " " # Deeper nesting
def _estimate_merged_cv(period1: dict, period2: dict) -> float | None:
"""
Estimate the CV of a merged period from two period summaries.
Since we don't have the raw prices, we estimate using the combined min/max range.
This is a conservative estimate - the actual CV could be higher or lower.
Formula: CV (range / 2) / mean * 100
Where range = max - min, mean = (min + max) / 2
This approximation assumes roughly uniform distribution within the range.
"""
p1_min = period1.get("price_min")
p1_max = period1.get("price_max")
p2_min = period2.get("price_min")
p2_max = period2.get("price_max")
if None in (p1_min, p1_max, p2_min, p2_max):
return None
# Cast to float - None case handled above
combined_min = min(float(p1_min), float(p2_min)) # type: ignore[arg-type]
combined_max = max(float(p1_max), float(p2_max)) # type: ignore[arg-type]
if combined_min <= 0:
return None
combined_mean = (combined_min + combined_max) / 2
price_range = combined_max - combined_min
# CV estimate based on range (assuming uniform distribution)
# For uniform distribution: std_dev ≈ range / sqrt(12) ≈ range / 3.46
return (price_range / 3.46) / combined_mean * 100
def recalculate_period_metadata(periods: list[dict], *, time: TibberPricesTimeService) -> None:
"""
Recalculate period metadata after merging periods.
Updates period_position, periods_total, and periods_remaining for all periods
based on chronological order.
This must be called after resolve_period_overlaps() to ensure metadata
reflects the final merged period list.
Args:
periods: List of period summary dicts (mutated in-place)
time: TibberPricesTimeService instance (required)
"""
if not periods:
return
# Sort periods chronologically by start time
periods.sort(key=lambda p: p.get("start") or time.now())
# Update metadata for all periods
total_periods = len(periods)
for position, period in enumerate(periods, 1):
period["period_position"] = position
period["periods_total"] = total_periods
period["periods_remaining"] = total_periods - position
def merge_adjacent_periods(period1: dict, period2: dict) -> dict:
"""
Merge two adjacent or overlapping periods into one.
The newer period's relaxation attributes override the older period's.
Takes the earliest start time and latest end time.
Relaxation attributes from the newer period (period2) override those from period1:
- relaxation_active
- relaxation_level
- relaxation_threshold_original_%
- relaxation_threshold_applied_%
- period_interval_level_gap_count
- period_interval_smoothed_count
Args:
period1: First period (older baseline or relaxed period)
period2: Second period (newer relaxed period with higher flex)
Returns:
Merged period dict with combined time span and newer period's attributes
"""
# Take earliest start and latest end
merged_start = min(period1["start"], period2["start"])
merged_end = max(period1["end"], period2["end"])
merged_duration = int((merged_end - merged_start).total_seconds() / 60)
# Start with period1 as base
merged = period1.copy()
# Update time boundaries
merged["start"] = merged_start
merged["end"] = merged_end
merged["duration_minutes"] = merged_duration
# Override with period2's relaxation attributes (newer/higher flex wins)
relaxation_attrs = [
"relaxation_active",
"relaxation_level",
"relaxation_threshold_original_%",
"relaxation_threshold_applied_%",
"period_interval_level_gap_count",
"period_interval_smoothed_count",
]
for attr in relaxation_attrs:
if attr in period2:
merged[attr] = period2[attr]
# Mark as merged (for debugging)
merged["merged_from"] = {
"period1_start": period1["start"].isoformat(),
"period1_end": period1["end"].isoformat(),
"period2_start": period2["start"].isoformat(),
"period2_end": period2["end"].isoformat(),
}
_LOGGER_DETAILS.debug(
"%sMerged periods: %s-%s + %s-%s%s-%s (duration: %d min)",
INDENT_L2,
period1["start"].strftime("%H:%M"),
period1["end"].strftime("%H:%M"),
period2["start"].strftime("%H:%M"),
period2["end"].strftime("%H:%M"),
merged_start.strftime("%H:%M"),
merged_end.strftime("%H:%M"),
merged_duration,
)
return merged
def _check_merge_quality_gate(periods_to_merge: list[tuple[int, dict]], relaxed: dict) -> bool:
"""
Check if merging would create a period that's too heterogeneous.
Returns True if merge is allowed, False if blocked by Quality Gate.
"""
from .types import PERIOD_MAX_CV # noqa: PLC0415
relaxed_start = relaxed["start"]
relaxed_end = relaxed["end"]
for _idx, existing in periods_to_merge:
estimated_cv = _estimate_merged_cv(existing, relaxed)
if estimated_cv is not None and estimated_cv > PERIOD_MAX_CV:
_LOGGER.debug(
"Merge blocked by Quality Gate: %s-%s + %s-%s would have CV≈%.1f%% (max: %.1f%%)",
existing["start"].strftime("%H:%M"),
existing["end"].strftime("%H:%M"),
relaxed_start.strftime("%H:%M"),
relaxed_end.strftime("%H:%M"),
estimated_cv,
PERIOD_MAX_CV,
)
return False
return True
def _would_swallow_existing(relaxed: dict, existing_periods: list[dict]) -> bool:
"""
Check if the relaxed period would "swallow" any existing period.
A period is "swallowed" if the new relaxed period completely contains it.
In this case, we should NOT merge - the existing smaller period is more
homogeneous and should be preserved.
This prevents relaxation from replacing good small periods with larger,
more heterogeneous ones.
Returns:
True if any existing period would be swallowed (merge should be blocked)
False if safe to proceed with merge evaluation
"""
relaxed_start = relaxed["start"]
relaxed_end = relaxed["end"]
for existing in existing_periods:
existing_start = existing["start"]
existing_end = existing["end"]
# Check if relaxed completely contains existing
if relaxed_start <= existing_start and relaxed_end >= existing_end:
_LOGGER.debug(
"Blocking merge: %s-%s would swallow %s-%s (keeping smaller period)",
relaxed_start.strftime("%H:%M"),
relaxed_end.strftime("%H:%M"),
existing_start.strftime("%H:%M"),
existing_end.strftime("%H:%M"),
)
return True
return False
def _is_duplicate_period(relaxed: dict, existing_periods: list[dict], tolerance_seconds: int = 60) -> bool:
"""Check if relaxed period is a duplicate of any existing period."""
relaxed_start = relaxed["start"]
relaxed_end = relaxed["end"]
for existing in existing_periods:
if (
abs((relaxed_start - existing["start"]).total_seconds()) < tolerance_seconds
and abs((relaxed_end - existing["end"]).total_seconds()) < tolerance_seconds
):
_LOGGER_DETAILS.debug(
"%sSkipping duplicate period %s-%s (already exists)",
INDENT_L1,
relaxed_start.strftime("%H:%M"),
relaxed_end.strftime("%H:%M"),
)
return True
return False
def _find_adjacent_or_overlapping(relaxed: dict, existing_periods: list[dict]) -> list[tuple[int, dict]]:
"""Find all periods that are adjacent to or overlapping with the relaxed period."""
relaxed_start = relaxed["start"]
relaxed_end = relaxed["end"]
periods_to_merge = []
for idx, existing in enumerate(existing_periods):
existing_start = existing["start"]
existing_end = existing["end"]
# Check if adjacent (no gap) or overlapping
is_adjacent = relaxed_end == existing_start or relaxed_start == existing_end
is_overlapping = relaxed_start < existing_end and relaxed_end > existing_start
if is_adjacent or is_overlapping:
periods_to_merge.append((idx, existing))
_LOGGER_DETAILS.debug(
"%sPeriod %s-%s %s with existing period %s-%s",
INDENT_L1,
relaxed_start.strftime("%H:%M"),
relaxed_end.strftime("%H:%M"),
"overlaps" if is_overlapping else "is adjacent to",
existing_start.strftime("%H:%M"),
existing_end.strftime("%H:%M"),
)
return periods_to_merge
def resolve_period_overlaps(
existing_periods: list[dict],
new_relaxed_periods: list[dict],
) -> tuple[list[dict], int]:
"""
Resolve overlaps between existing periods and newly found relaxed periods.
Adjacent or overlapping periods are merged into single continuous periods.
The newer period's relaxation attributes override the older period's.
Quality Gate: Merging is blocked if the combined period would have
an estimated CV above PERIOD_MAX_CV (25%), to prevent creating
periods with excessive internal price variation.
This function is called incrementally after each relaxation phase:
- Phase 1: existing = baseline, new = first relaxation
- Phase 2: existing = baseline + phase 1, new = second relaxation
- Phase 3: existing = baseline + phase 1 + phase 2, new = third relaxation
Args:
existing_periods: All previously found periods (baseline + earlier relaxation phases)
new_relaxed_periods: Periods found in current relaxation phase (will be merged if adjacent)
Returns:
Tuple of (merged_periods, new_periods_count):
- merged_periods: All periods after merging, sorted by start time
- new_periods_count: Number of new periods added (some may have been merged)
"""
_LOGGER_DETAILS.debug(
"%sresolve_period_overlaps called: existing=%d, new=%d",
INDENT_L0,
len(existing_periods),
len(new_relaxed_periods),
)
if not new_relaxed_periods:
return existing_periods.copy(), 0
if not existing_periods:
# No existing periods - return all new periods
return new_relaxed_periods.copy(), len(new_relaxed_periods)
merged = existing_periods.copy()
periods_added = 0
for relaxed in new_relaxed_periods:
relaxed_start = relaxed["start"]
relaxed_end = relaxed["end"]
# Check if this period is duplicate (exact match within tolerance)
if _is_duplicate_period(relaxed, merged):
continue
# Check if this period would "swallow" an existing smaller period
# In that case, skip it - the smaller existing period is more homogeneous
if _would_swallow_existing(relaxed, merged):
continue
# Find periods that are adjacent or overlapping (should be merged)
periods_to_merge = _find_adjacent_or_overlapping(relaxed, merged)
if not periods_to_merge:
# No merge needed - add as new period
merged.append(relaxed)
periods_added += 1
_LOGGER_DETAILS.debug(
"%sAdded new period %s-%s (no overlap/adjacency)",
INDENT_L1,
relaxed_start.strftime("%H:%M"),
relaxed_end.strftime("%H:%M"),
)
continue
# Quality Gate: Check if merging would create a period that's too heterogeneous
should_merge = _check_merge_quality_gate(periods_to_merge, relaxed)
if not should_merge:
# Don't merge - add as separate period instead
merged.append(relaxed)
periods_added += 1
_LOGGER_DETAILS.debug(
"%sAdded new period %s-%s separately (merge blocked by CV gate)",
INDENT_L1,
relaxed_start.strftime("%H:%M"),
relaxed_end.strftime("%H:%M"),
)
continue
# Merge with all adjacent/overlapping periods
# Start with the new relaxed period
merged_period = relaxed.copy()
# Remove old periods (in reverse order to maintain indices)
for idx, existing in reversed(periods_to_merge):
merged_period = merge_adjacent_periods(existing, merged_period)
merged.pop(idx)
# Add the merged result
merged.append(merged_period)
# Count as added if we merged exactly one existing period
# (means we extended/merged, not replaced multiple)
if len(periods_to_merge) == 1:
periods_added += 1
# Sort all periods by start time
merged.sort(key=lambda p: p["start"])
return merged, periods_added

View file

@ -7,25 +7,24 @@ from typing import TYPE_CHECKING, Any
if TYPE_CHECKING:
from datetime import datetime
from custom_components.tibber_prices.coordinator.time_service import TibberPricesTimeService
from .types import (
TibberPricesPeriodData,
TibberPricesPeriodStatistics,
TibberPricesThresholdConfig,
PeriodData,
PeriodStatistics,
ThresholdConfig,
)
from custom_components.tibber_prices.utils.average import calculate_median
from custom_components.tibber_prices.utils.price import (
aggregate_period_levels,
aggregate_period_ratings,
calculate_coefficient_of_variation,
calculate_volatility_level,
)
from homeassistant.util import dt as dt_util
from .types import MINUTES_PER_INTERVAL
def calculate_period_price_diff(
price_mean: float,
price_avg: float,
start_time: datetime,
price_context: dict[str, Any],
) -> tuple[float | None, float | None]:
@ -34,11 +33,6 @@ def calculate_period_price_diff(
Uses reference price from start day of the period for consistency.
Args:
price_mean: Mean price of the period (in base currency).
start_time: Start time of the period.
price_context: Dictionary with ref_prices per day.
Returns:
Tuple of (period_price_diff, period_price_diff_pct) or (None, None) if no reference available.
@ -53,14 +47,12 @@ def calculate_period_price_diff(
if ref_price is None:
return None, None
# Both prices are in base currency, no conversion needed
ref_price_display = round(ref_price, 4)
period_price_diff = round(price_mean - ref_price_display, 4)
# Convert reference price to minor units (ct/øre)
ref_price_minor = round(ref_price * 100, 2)
period_price_diff = round(price_avg - ref_price_minor, 2)
period_price_diff_pct = None
if ref_price_display != 0:
# CRITICAL: Use abs() for negative prices (same logic as calculate_difference_percentage)
# Example: avg=-10, ref=-20 → diff=10, pct=10/abs(-20)*100=+50% (correctly shows more expensive)
period_price_diff_pct = round((period_price_diff / abs(ref_price_display)) * 100, 2)
if ref_price_minor != 0:
period_price_diff_pct = round((period_price_diff / ref_price_minor) * 100, 2)
return period_price_diff, period_price_diff_pct
@ -90,44 +82,34 @@ def calculate_aggregated_rating_difference(period_price_data: list[dict]) -> flo
return round(sum(differences) / len(differences), 2)
def calculate_period_price_statistics(
period_price_data: list[dict],
) -> dict[str, float]:
def calculate_period_price_statistics(period_price_data: list[dict]) -> dict[str, float]:
"""
Calculate price statistics for a period.
Args:
period_price_data: List of price data dictionaries with "total" field.
period_price_data: List of price data dictionaries with "total" field
Returns:
Dictionary with price_mean, price_median, price_min, price_max, price_spread (all in base currency).
Note: price_spread is calculated based on price_mean (max - min range as percentage of mean).
Dictionary with price_avg, price_min, price_max, price_spread (all in minor units: ct/øre)
"""
# Keep prices in base currency (Euro/NOK/SEK) for internal storage
# Conversion to display units (ct/øre) happens in services/formatting layer
factor = 1 # Always use base currency for storage
prices_display = [round(float(p["total"]) * factor, 4) for p in period_price_data]
prices_minor = [round(float(p["total"]) * 100, 2) for p in period_price_data]
if not prices_display:
if not prices_minor:
return {
"price_mean": 0.0,
"price_median": 0.0,
"price_avg": 0.0,
"price_min": 0.0,
"price_max": 0.0,
"price_spread": 0.0,
}
price_mean = round(sum(prices_display) / len(prices_display), 4)
median_value = calculate_median(prices_display)
price_median = round(median_value, 4) if median_value is not None else 0.0
price_min = round(min(prices_display), 4)
price_max = round(max(prices_display), 4)
price_spread = round(price_max - price_min, 4)
price_avg = round(sum(prices_minor) / len(prices_minor), 2)
price_min = round(min(prices_minor), 2)
price_max = round(max(prices_minor), 2)
price_spread = round(price_max - price_min, 2)
return {
"price_mean": price_mean,
"price_median": price_median,
"price_avg": price_avg,
"price_min": price_min,
"price_max": price_max,
"price_spread": price_spread,
@ -135,11 +117,10 @@ def calculate_period_price_statistics(
def build_period_summary_dict(
period_data: TibberPricesPeriodData,
stats: TibberPricesPeriodStatistics,
period_data: PeriodData,
stats: PeriodStatistics,
*,
reverse_sort: bool,
price_context: dict[str, Any] | None = None,
) -> dict:
"""
Build the complete period summary dictionary.
@ -148,7 +129,6 @@ def build_period_summary_dict(
period_data: Period timing and position data
stats: Calculated period statistics
reverse_sort: True for peak price, False for best price (keyword-only)
price_context: Optional dict with ref_prices, avg_prices, intervals_by_day for day statistics
Returns:
Complete period summary dictionary following attribute ordering
@ -159,18 +139,16 @@ def build_period_summary_dict(
# 1. Time information (when does this apply?)
"start": period_data.start_time,
"end": period_data.end_time,
"duration_minutes": period_data.period_length * 15, # period_length is in intervals
"duration_minutes": period_data.period_length * MINUTES_PER_INTERVAL,
# 2. Core decision attributes (what should I do?)
"level": stats.aggregated_level,
"rating_level": stats.aggregated_rating,
"rating_difference_%": stats.rating_difference_pct,
# 3. Price statistics (how much does it cost?)
"price_mean": stats.price_mean,
"price_median": stats.price_median,
"price_avg": stats.price_avg,
"price_min": stats.price_min,
"price_max": stats.price_max,
"price_spread": stats.price_spread,
"price_coefficient_variation_%": stats.coefficient_of_variation,
"volatility": stats.volatility,
# 4. Price differences will be added below if available
# 5. Detail information (additional context)
@ -193,30 +171,6 @@ def build_period_summary_dict(
if stats.period_price_diff_pct is not None:
summary["period_price_diff_from_daily_min_%"] = stats.period_price_diff_pct
# Add day volatility and price statistics (for understanding midnight classification changes)
if price_context:
period_start_date = period_data.start_time.date()
intervals_by_day = price_context.get("intervals_by_day", {})
avg_prices = price_context.get("avg_prices", {})
day_intervals = intervals_by_day.get(period_start_date, [])
if day_intervals:
# Calculate day price statistics (in EUR major units from API)
day_prices = [float(p["total"]) for p in day_intervals]
day_min = min(day_prices)
day_max = max(day_prices)
day_span = day_max - day_min
day_avg = avg_prices.get(period_start_date, sum(day_prices) / len(day_prices))
# Calculate volatility percentage (span / avg * 100)
day_volatility_pct = round((day_span / day_avg * 100), 1) if day_avg > 0 else 0.0
# Convert to minor units (ct/øre) for consistency with other price attributes
summary["day_volatility_%"] = day_volatility_pct
summary["day_price_min"] = round(day_min * 100, 2)
summary["day_price_max"] = round(day_max * 100, 2)
summary["day_price_span"] = round(day_span * 100, 2)
return summary
@ -224,16 +178,14 @@ def extract_period_summaries(
periods: list[list[dict]],
all_prices: list[dict],
price_context: dict[str, Any],
thresholds: TibberPricesThresholdConfig,
*,
time: TibberPricesTimeService,
thresholds: ThresholdConfig,
) -> list[dict]:
"""
Extract complete period summaries with all aggregated attributes.
Returns sensor-ready period summaries with:
- Timestamps and positioning (start, end, hour, minute, time)
- Aggregated price statistics (price_mean, price_median, price_min, price_max, price_spread)
- Aggregated price statistics (price_avg, price_min, price_max, price_spread)
- Volatility categorization (low/moderate/high/very_high based on coefficient of variation)
- Rating difference percentage (aggregated from intervals)
- Period price differences (period_price_diff_from_daily_min/max)
@ -243,23 +195,23 @@ def extract_period_summaries(
All data is pre-calculated and ready for display - no further processing needed.
Args:
periods: List of periods, where each period is a list of interval dictionaries.
all_prices: All price data from the API (enriched with level, difference, rating_level).
price_context: Dictionary with ref_prices and avg_prices per day.
thresholds: Threshold configuration for calculations.
time: TibberPricesTimeService instance (required).
periods: List of periods, where each period is a list of interval dictionaries
all_prices: All price data from the API (enriched with level, difference, rating_level)
price_context: Dictionary with ref_prices and avg_prices per day
thresholds: Threshold configuration for calculations
"""
from .types import ( # noqa: PLC0415 - Avoid circular import
TibberPricesPeriodData,
TibberPricesPeriodStatistics,
PeriodData,
PeriodStatistics,
)
# Build lookup dictionary for full price data by timestamp
price_lookup: dict[str, dict] = {}
for price_data in all_prices:
starts_at = time.get_interval_time(price_data)
starts_at = dt_util.parse_datetime(price_data["startsAt"])
if starts_at:
starts_at = dt_util.as_local(starts_at)
price_lookup[starts_at.isoformat()] = price_data
summaries = []
@ -305,21 +257,18 @@ def extract_period_summaries(
thresholds.threshold_high,
)
# Calculate price statistics (in base currency, conversion happens in presentation layer)
# Calculate price statistics (in minor units: ct/øre)
price_stats = calculate_period_price_statistics(period_price_data)
# Calculate period price difference from daily reference
period_price_diff, period_price_diff_pct = calculate_period_price_diff(
price_stats["price_mean"], start_time, price_context
price_stats["price_avg"], start_time, price_context
)
# Extract prices for volatility calculation (coefficient of variation)
prices_for_volatility = [float(p["total"]) for p in period_price_data if "total" in p]
# Calculate CV (numeric) for quality gate checks
period_cv = calculate_coefficient_of_variation(prices_for_volatility)
# Calculate volatility (categorical) using thresholds
# Calculate volatility (categorical) and aggregated rating difference (numeric)
volatility = calculate_volatility_level(
prices_for_volatility,
threshold_moderate=thresholds.threshold_volatility_moderate,
@ -335,7 +284,7 @@ def extract_period_summaries(
level_gap_count = sum(1 for interval in period if interval.get("is_level_gap", False))
# Build period data and statistics objects
period_data = TibberPricesPeriodData(
period_data = PeriodData(
start_time=start_time,
end_time=end_time,
period_length=len(period),
@ -343,25 +292,21 @@ def extract_period_summaries(
total_periods=total_periods,
)
stats = TibberPricesPeriodStatistics(
stats = PeriodStatistics(
aggregated_level=aggregated_level,
aggregated_rating=aggregated_rating,
rating_difference_pct=rating_difference_pct,
price_mean=price_stats["price_mean"],
price_median=price_stats["price_median"],
price_avg=price_stats["price_avg"],
price_min=price_stats["price_min"],
price_max=price_stats["price_max"],
price_spread=price_stats["price_spread"],
volatility=volatility,
coefficient_of_variation=round(period_cv, 1) if period_cv is not None else None,
period_price_diff=period_price_diff,
period_price_diff_pct=period_price_diff_pct,
)
# Build complete period summary
summary = build_period_summary_dict(
period_data, stats, reverse_sort=thresholds.reverse_sort, price_context=price_context
)
summary = build_period_summary_dict(period_data, stats, reverse_sort=thresholds.reverse_sort)
# Add smoothing information if any intervals benefited from smoothing
if smoothed_impactful_count > 0:

View file

@ -13,26 +13,9 @@ from custom_components.tibber_prices.const import (
DEFAULT_VOLATILITY_THRESHOLD_HIGH,
DEFAULT_VOLATILITY_THRESHOLD_MODERATE,
DEFAULT_VOLATILITY_THRESHOLD_VERY_HIGH,
MINUTES_PER_INTERVAL, # noqa: F401 - Re-exported for period handler modules
)
# Quality Gate: Maximum coefficient of variation (CV) allowed within a period
# Periods with internal CV above this are considered too heterogeneous for "best price"
# A 25% CV means the std dev is 25% of the mean - beyond this, prices vary too much
# Example: Period with prices 0.7-0.99 kr has ~15% CV which is acceptable
# Period with prices 0.5-1.0 kr has ~30% CV which would be rejected
PERIOD_MAX_CV = 25.0 # 25% max coefficient of variation within a period
# Cross-Day Extension: Time window constants
# When a period ends late in the day and tomorrow data is available,
# we can extend it past midnight if prices remain favorable
CROSS_DAY_LATE_PERIOD_START_HOUR = 20 # Consider periods starting at 20:00 or later for extension
CROSS_DAY_MAX_EXTENSION_HOUR = 8 # Don't extend beyond 08:00 next day (covers typical night low)
# Cross-Day Supersession: When tomorrow data arrives, late-night periods that are
# worse than early-morning tomorrow periods become obsolete
# A today period is "superseded" if tomorrow has a significantly better alternative
SUPERSESSION_PRICE_IMPROVEMENT_PCT = 10.0 # Tomorrow must be at least 10% cheaper to supersede
# Log indentation levels for visual hierarchy
INDENT_L0 = "" # Top level (calculate_periods_with_relaxation)
INDENT_L1 = " " # Per-day loop
@ -42,7 +25,7 @@ INDENT_L4 = " " # Period-by-period analysis
INDENT_L5 = " " # Segment details
class TibberPricesPeriodConfig(NamedTuple):
class PeriodConfig(NamedTuple):
"""Configuration for period calculation."""
reverse_sort: bool
@ -58,7 +41,7 @@ class TibberPricesPeriodConfig(NamedTuple):
gap_count: int = 0 # Number of allowed consecutive deviating intervals
class TibberPricesPeriodData(NamedTuple):
class PeriodData(NamedTuple):
"""Data for building a period summary."""
start_time: datetime
@ -68,24 +51,22 @@ class TibberPricesPeriodData(NamedTuple):
total_periods: int
class TibberPricesPeriodStatistics(NamedTuple):
class PeriodStatistics(NamedTuple):
"""Calculated statistics for a period."""
aggregated_level: str | None
aggregated_rating: str | None
rating_difference_pct: float | None
price_mean: float
price_median: float
price_avg: float
price_min: float
price_max: float
price_spread: float
volatility: str
coefficient_of_variation: float | None # CV as percentage (e.g., 15.0 for 15%)
period_price_diff: float | None
period_price_diff_pct: float | None
class TibberPricesThresholdConfig(NamedTuple):
class ThresholdConfig(NamedTuple):
"""Threshold configuration for period calculations."""
threshold_low: float | None
@ -96,7 +77,7 @@ class TibberPricesThresholdConfig(NamedTuple):
reverse_sort: bool
class TibberPricesIntervalCriteria(NamedTuple):
class IntervalCriteria(NamedTuple):
"""Criteria for checking if an interval qualifies for a period."""
ref_price: float

View file

@ -12,70 +12,35 @@ from typing import TYPE_CHECKING, Any
from custom_components.tibber_prices import const as _const
if TYPE_CHECKING:
from collections.abc import Callable
from custom_components.tibber_prices.coordinator.time_service import TibberPricesTimeService
from homeassistant.config_entries import ConfigEntry
from .helpers import get_intervals_for_day_offsets
from .period_handlers import (
TibberPricesPeriodConfig,
PeriodConfig,
calculate_periods_with_relaxation,
)
if TYPE_CHECKING:
from homeassistant.config_entries import ConfigEntry
_LOGGER = logging.getLogger(__name__)
class TibberPricesPeriodCalculator:
class PeriodCalculator:
"""Handles period calculations with level filtering and gap tolerance."""
def __init__(
self,
config_entry: ConfigEntry,
log_prefix: str,
get_config_override_fn: Callable[[str, str], Any | None] | None = None,
) -> None:
"""Initialize the period calculator."""
self.config_entry = config_entry
self._log_prefix = log_prefix
self.time: TibberPricesTimeService # Set by coordinator before first use
self._config_cache: dict[str, dict[str, Any]] | None = None
self._config_cache_valid = False
self._get_config_override = get_config_override_fn
# Period calculation cache
self._cached_periods: dict[str, Any] | None = None
self._last_periods_hash: str | None = None
def _get_option(
self,
config_key: str,
config_section: str,
default: Any,
) -> Any:
"""
Get a config option, checking overrides first.
Args:
config_key: The configuration key
config_section: The section in options (e.g., "flexibility_settings")
default: Default value if not set
Returns:
Override value if set, otherwise options value, otherwise default
"""
# Check overrides first
if self._get_config_override is not None:
override = self._get_config_override(config_key, config_section)
if override is not None:
return override
# Fall back to options
section = self.config_entry.options.get(config_section, {})
return section.get(config_key, default)
def _log(self, level: str, message: str, *args: object, **kwargs: object) -> None:
"""Log with calculator-specific prefix."""
prefixed_message = f"{self._log_prefix} {message}"
@ -95,7 +60,7 @@ class TibberPricesPeriodCalculator:
Compute hash of price data and config for period calculation caching.
Only includes data that affects period calculation:
- All interval timestamps and enriched rating levels (yesterday/today/tomorrow)
- Today's interval timestamps and enriched rating levels
- Period calculation config (flex, min_distance, min_period_length)
- Level filter overrides
@ -103,20 +68,9 @@ class TibberPricesPeriodCalculator:
Hash string for cache key comparison.
"""
# Get today and tomorrow intervals for hash calculation
# CRITICAL: Only today+tomorrow needed in hash because:
# 1. Mitternacht: "today" startsAt changes → cache invalidates
# 2. Tomorrow arrival: "tomorrow" startsAt changes from None → cache invalidates
# 3. Yesterday/day-before-yesterday are static (rating_levels don't change retroactively)
# 4. Using first startsAt as representative (changes → entire day changed)
coordinator_data = {"priceInfo": price_info}
today_intervals = get_intervals_for_day_offsets(coordinator_data, [0])
tomorrow_intervals = get_intervals_for_day_offsets(coordinator_data, [1])
# Use first startsAt of each day as representative for entire day's data
# If day is empty, use None (detects data availability changes)
today_start = today_intervals[0].get("startsAt") if today_intervals else None
tomorrow_start = tomorrow_intervals[0].get("startsAt") if tomorrow_intervals else None
# Get relevant price data
today = price_info.get("today", [])
today_signature = tuple((interval.get("startsAt"), interval.get("rating_level")) for interval in today)
# Get period configs (both best and peak)
best_config = self.get_period_config(reverse_sort=False)
@ -124,14 +78,12 @@ class TibberPricesPeriodCalculator:
# Get level filter overrides from options
options = self.config_entry.options
period_settings = options.get("period_settings", {})
best_level_filter = period_settings.get(_const.CONF_BEST_PRICE_MAX_LEVEL, _const.DEFAULT_BEST_PRICE_MAX_LEVEL)
peak_level_filter = period_settings.get(_const.CONF_PEAK_PRICE_MIN_LEVEL, _const.DEFAULT_PEAK_PRICE_MIN_LEVEL)
best_level_filter = options.get(_const.CONF_BEST_PRICE_MAX_LEVEL, _const.DEFAULT_BEST_PRICE_MAX_LEVEL)
peak_level_filter = options.get(_const.CONF_PEAK_PRICE_MIN_LEVEL, _const.DEFAULT_PEAK_PRICE_MIN_LEVEL)
# Compute hash from all relevant data
hash_data = (
today_start, # Representative for today's data (changes at midnight)
tomorrow_start, # Representative for tomorrow's data (changes when data arrives)
today_signature,
tuple(best_config.items()),
tuple(peak_config.items()),
best_level_filter,
@ -144,7 +96,7 @@ class TibberPricesPeriodCalculator:
Get period calculation configuration from config options.
Uses cached config to avoid multiple options.get() calls.
Cache is invalidated when config_entry.options change or override entities update.
Cache is invalidated when config_entry.options change.
"""
cache_key = "peak" if reverse_sort else "best"
@ -156,72 +108,45 @@ class TibberPricesPeriodCalculator:
if self._config_cache is None:
self._config_cache = {}
# Get config values, checking overrides first
# CRITICAL: Best/Peak price settings are stored in nested sections:
# - period_settings: min_period_length, max_level, gap_count
# - flexibility_settings: flex, min_distance_from_avg
# Override entities can override any of these values at runtime
options = self.config_entry.options
data = self.config_entry.data
if reverse_sort:
# Peak price configuration
flex = self._get_option(
_const.CONF_PEAK_PRICE_FLEX,
"flexibility_settings",
_const.DEFAULT_PEAK_PRICE_FLEX,
flex = options.get(
_const.CONF_PEAK_PRICE_FLEX, data.get(_const.CONF_PEAK_PRICE_FLEX, _const.DEFAULT_PEAK_PRICE_FLEX)
)
min_distance_from_avg = self._get_option(
min_distance_from_avg = options.get(
_const.CONF_PEAK_PRICE_MIN_DISTANCE_FROM_AVG,
"flexibility_settings",
_const.DEFAULT_PEAK_PRICE_MIN_DISTANCE_FROM_AVG,
data.get(_const.CONF_PEAK_PRICE_MIN_DISTANCE_FROM_AVG, _const.DEFAULT_PEAK_PRICE_MIN_DISTANCE_FROM_AVG),
)
min_period_length = self._get_option(
min_period_length = options.get(
_const.CONF_PEAK_PRICE_MIN_PERIOD_LENGTH,
"period_settings",
_const.DEFAULT_PEAK_PRICE_MIN_PERIOD_LENGTH,
data.get(_const.CONF_PEAK_PRICE_MIN_PERIOD_LENGTH, _const.DEFAULT_PEAK_PRICE_MIN_PERIOD_LENGTH),
)
else:
# Best price configuration
flex = self._get_option(
_const.CONF_BEST_PRICE_FLEX,
"flexibility_settings",
_const.DEFAULT_BEST_PRICE_FLEX,
flex = options.get(
_const.CONF_BEST_PRICE_FLEX, data.get(_const.CONF_BEST_PRICE_FLEX, _const.DEFAULT_BEST_PRICE_FLEX)
)
min_distance_from_avg = self._get_option(
min_distance_from_avg = options.get(
_const.CONF_BEST_PRICE_MIN_DISTANCE_FROM_AVG,
"flexibility_settings",
_const.DEFAULT_BEST_PRICE_MIN_DISTANCE_FROM_AVG,
data.get(_const.CONF_BEST_PRICE_MIN_DISTANCE_FROM_AVG, _const.DEFAULT_BEST_PRICE_MIN_DISTANCE_FROM_AVG),
)
min_period_length = self._get_option(
min_period_length = options.get(
_const.CONF_BEST_PRICE_MIN_PERIOD_LENGTH,
"period_settings",
_const.DEFAULT_BEST_PRICE_MIN_PERIOD_LENGTH,
data.get(_const.CONF_BEST_PRICE_MIN_PERIOD_LENGTH, _const.DEFAULT_BEST_PRICE_MIN_PERIOD_LENGTH),
)
# Convert flex from percentage to decimal (e.g., 5 -> 0.05)
# CRITICAL: Normalize to absolute value for internal calculations
# User-facing values use sign convention:
# - Best price: positive (e.g., +15% above minimum)
# - Peak price: negative (e.g., -20% below maximum)
# Internal calculations always use positive values with reverse_sort flag
try:
flex = abs(float(flex)) / 100 # Always positive internally
flex = float(flex) / 100
except (TypeError, ValueError):
flex = (
abs(_const.DEFAULT_BEST_PRICE_FLEX) / 100
if not reverse_sort
else abs(_const.DEFAULT_PEAK_PRICE_FLEX) / 100
)
# CRITICAL: Normalize min_distance_from_avg to absolute value
# User-facing values use sign convention:
# - Best price: negative (e.g., -5% below average)
# - Peak price: positive (e.g., +5% above average)
# Internal calculations always use positive values with reverse_sort flag
min_distance_from_avg_normalized = abs(float(min_distance_from_avg))
flex = _const.DEFAULT_BEST_PRICE_FLEX / 100 if not reverse_sort else _const.DEFAULT_PEAK_PRICE_FLEX / 100
config = {
"flex": flex,
"min_distance_from_avg": min_distance_from_avg_normalized,
"min_distance_from_avg": float(min_distance_from_avg),
"min_period_length": int(min_period_length),
}
@ -400,19 +325,18 @@ class TibberPricesPeriodCalculator:
# Normal check failed - try splitting at gap clusters as fallback
# Get minimum period length from config (convert minutes to intervals)
period_settings = self.config_entry.options.get("period_settings", {})
if reverse_sort:
min_period_minutes = period_settings.get(
min_period_minutes = self.config_entry.options.get(
_const.CONF_PEAK_PRICE_MIN_PERIOD_LENGTH,
_const.DEFAULT_PEAK_PRICE_MIN_PERIOD_LENGTH,
)
else:
min_period_minutes = period_settings.get(
min_period_minutes = self.config_entry.options.get(
_const.CONF_BEST_PRICE_MIN_PERIOD_LENGTH,
_const.DEFAULT_BEST_PRICE_MIN_PERIOD_LENGTH,
)
min_period_intervals = self.time.minutes_to_intervals(min_period_minutes)
min_period_intervals = min_period_minutes // 15
sub_sequences = self.split_at_gap_clusters(
today_intervals,
@ -532,15 +456,13 @@ class TibberPricesPeriodCalculator:
# Get appropriate config based on sensor type
elif reverse_sort:
# Peak price: minimum level filter (lower bound)
period_settings = self.config_entry.options.get("period_settings", {})
level_config = period_settings.get(
level_config = self.config_entry.options.get(
_const.CONF_PEAK_PRICE_MIN_LEVEL,
_const.DEFAULT_PEAK_PRICE_MIN_LEVEL,
)
else:
# Best price: maximum level filter (upper bound)
period_settings = self.config_entry.options.get("period_settings", {})
level_config = period_settings.get(
level_config = self.config_entry.options.get(
_const.CONF_BEST_PRICE_MAX_LEVEL,
_const.DEFAULT_BEST_PRICE_MAX_LEVEL,
)
@ -549,23 +471,20 @@ class TibberPricesPeriodCalculator:
if level_config == "any":
return True
# Get today's intervals from flat list
# Build minimal coordinator_data structure for get_intervals_for_day_offsets
coordinator_data = {"priceInfo": price_info}
today_intervals = get_intervals_for_day_offsets(coordinator_data, [0])
# Get today's intervals
today_intervals = price_info.get("today", [])
if not today_intervals:
return True # If no data, don't filter
# Get gap tolerance configuration
period_settings = self.config_entry.options.get("period_settings", {})
if reverse_sort:
max_gap_count = period_settings.get(
max_gap_count = self.config_entry.options.get(
_const.CONF_PEAK_PRICE_MAX_LEVEL_GAP_COUNT,
_const.DEFAULT_PEAK_PRICE_MAX_LEVEL_GAP_COUNT,
)
else:
max_gap_count = period_settings.get(
max_gap_count = self.config_entry.options.get(
_const.CONF_BEST_PRICE_MAX_LEVEL_GAP_COUNT,
_const.DEFAULT_BEST_PRICE_MAX_LEVEL_GAP_COUNT,
)
@ -595,7 +514,7 @@ class TibberPricesPeriodCalculator:
reverse_sort=reverse_sort,
)
def calculate_periods_for_price_info(
def calculate_periods_for_price_info( # noqa: PLR0915
self,
price_info: dict[str, Any],
) -> dict[str, Any]:
@ -616,14 +535,12 @@ class TibberPricesPeriodCalculator:
self._log("debug", "Calculating periods (cache miss or hash mismatch)")
# Get all intervals at once (day before yesterday + yesterday + today + tomorrow)
# CRITICAL: 4 days ensure stable historical period calculations
# (periods calculated today for yesterday match periods calculated yesterday)
coordinator_data = {"priceInfo": price_info}
all_prices = get_intervals_for_day_offsets(coordinator_data, [-2, -1, 0, 1])
yesterday_prices = price_info.get("yesterday", [])
today_prices = price_info.get("today", [])
tomorrow_prices = price_info.get("tomorrow", [])
all_prices = yesterday_prices + today_prices + tomorrow_prices
# Get rating thresholds from config (flat in options, not in sections)
# CRITICAL: Price rating thresholds are stored FLAT in options (no sections)
# Get rating thresholds from config
threshold_low = self.config_entry.options.get(
_const.CONF_PRICE_RATING_THRESHOLD_LOW,
_const.DEFAULT_PRICE_RATING_THRESHOLD_LOW,
@ -633,8 +550,7 @@ class TibberPricesPeriodCalculator:
_const.DEFAULT_PRICE_RATING_THRESHOLD_HIGH,
)
# Get volatility thresholds from config (flat in options, not in sections)
# CRITICAL: Volatility thresholds are stored FLAT in options (no sections)
# Get volatility thresholds from config
threshold_volatility_moderate = self.config_entry.options.get(
_const.CONF_VOLATILITY_THRESHOLD_MODERATE,
_const.DEFAULT_VOLATILITY_THRESHOLD_MODERATE,
@ -649,11 +565,8 @@ class TibberPricesPeriodCalculator:
)
# Get relaxation configuration for best price
# CRITICAL: Relaxation settings are stored in nested section 'relaxation_and_target_periods'
# Override entities can override any of these values at runtime
enable_relaxation_best = self._get_option(
enable_relaxation_best = self.config_entry.options.get(
_const.CONF_ENABLE_MIN_PERIODS_BEST,
"relaxation_and_target_periods",
_const.DEFAULT_ENABLE_MIN_PERIODS_BEST,
)
@ -664,33 +577,32 @@ class TibberPricesPeriodCalculator:
show_best_price = bool(all_prices)
else:
show_best_price = self.should_show_periods(price_info, reverse_sort=False) if all_prices else False
min_periods_best = self._get_option(
min_periods_best = self.config_entry.options.get(
_const.CONF_MIN_PERIODS_BEST,
"relaxation_and_target_periods",
_const.DEFAULT_MIN_PERIODS_BEST,
)
relaxation_attempts_best = self._get_option(
relaxation_step_best = self.config_entry.options.get(
_const.CONF_RELAXATION_STEP_BEST,
_const.DEFAULT_RELAXATION_STEP_BEST,
)
relaxation_attempts_best = self.config_entry.options.get(
_const.CONF_RELAXATION_ATTEMPTS_BEST,
"relaxation_and_target_periods",
_const.DEFAULT_RELAXATION_ATTEMPTS_BEST,
)
# Calculate best price periods (or return empty if filtered)
if show_best_price:
best_config = self.get_period_config(reverse_sort=False)
# Get level filter configuration from period_settings section
# CRITICAL: max_level and gap_count are stored in nested section 'period_settings'
max_level_best = self._get_option(
# Get level filter configuration
max_level_best = self.config_entry.options.get(
_const.CONF_BEST_PRICE_MAX_LEVEL,
"period_settings",
_const.DEFAULT_BEST_PRICE_MAX_LEVEL,
)
gap_count_best = self._get_option(
gap_count_best = self.config_entry.options.get(
_const.CONF_BEST_PRICE_MAX_LEVEL_GAP_COUNT,
"period_settings",
_const.DEFAULT_BEST_PRICE_MAX_LEVEL_GAP_COUNT,
)
best_period_config = TibberPricesPeriodConfig(
best_period_config = PeriodConfig(
reverse_sort=False,
flex=best_config["flex"],
min_distance_from_avg=best_config["min_distance_from_avg"],
@ -703,38 +615,30 @@ class TibberPricesPeriodCalculator:
level_filter=max_level_best,
gap_count=gap_count_best,
)
best_periods = calculate_periods_with_relaxation(
best_periods, best_relaxation = calculate_periods_with_relaxation(
all_prices,
config=best_period_config,
enable_relaxation=enable_relaxation_best,
min_periods=min_periods_best,
relaxation_step_pct=relaxation_step_best,
max_relaxation_attempts=relaxation_attempts_best,
should_show_callback=lambda lvl: self.should_show_periods(
price_info,
reverse_sort=False,
level_override=lvl,
),
time=self.time,
config_entry=self.config_entry,
)
else:
best_periods = {
"periods": [],
"intervals": [],
"metadata": {
"total_intervals": 0,
"total_periods": 0,
"config": {},
"relaxation": {"relaxation_active": False, "relaxation_attempted": False},
},
"metadata": {"total_intervals": 0, "total_periods": 0, "config": {}},
}
best_relaxation = {"relaxation_active": False, "relaxation_attempted": False}
# Get relaxation configuration for peak price
# CRITICAL: Relaxation settings are stored in nested section 'relaxation_and_target_periods'
# Override entities can override any of these values at runtime
enable_relaxation_peak = self._get_option(
enable_relaxation_peak = self.config_entry.options.get(
_const.CONF_ENABLE_MIN_PERIODS_PEAK,
"relaxation_and_target_periods",
_const.DEFAULT_ENABLE_MIN_PERIODS_PEAK,
)
@ -745,33 +649,32 @@ class TibberPricesPeriodCalculator:
show_peak_price = bool(all_prices)
else:
show_peak_price = self.should_show_periods(price_info, reverse_sort=True) if all_prices else False
min_periods_peak = self._get_option(
min_periods_peak = self.config_entry.options.get(
_const.CONF_MIN_PERIODS_PEAK,
"relaxation_and_target_periods",
_const.DEFAULT_MIN_PERIODS_PEAK,
)
relaxation_attempts_peak = self._get_option(
relaxation_step_peak = self.config_entry.options.get(
_const.CONF_RELAXATION_STEP_PEAK,
_const.DEFAULT_RELAXATION_STEP_PEAK,
)
relaxation_attempts_peak = self.config_entry.options.get(
_const.CONF_RELAXATION_ATTEMPTS_PEAK,
"relaxation_and_target_periods",
_const.DEFAULT_RELAXATION_ATTEMPTS_PEAK,
)
# Calculate peak price periods (or return empty if filtered)
if show_peak_price:
peak_config = self.get_period_config(reverse_sort=True)
# Get level filter configuration from period_settings section
# CRITICAL: min_level and gap_count are stored in nested section 'period_settings'
min_level_peak = self._get_option(
# Get level filter configuration
min_level_peak = self.config_entry.options.get(
_const.CONF_PEAK_PRICE_MIN_LEVEL,
"period_settings",
_const.DEFAULT_PEAK_PRICE_MIN_LEVEL,
)
gap_count_peak = self._get_option(
gap_count_peak = self.config_entry.options.get(
_const.CONF_PEAK_PRICE_MAX_LEVEL_GAP_COUNT,
"period_settings",
_const.DEFAULT_PEAK_PRICE_MAX_LEVEL_GAP_COUNT,
)
peak_period_config = TibberPricesPeriodConfig(
peak_period_config = PeriodConfig(
reverse_sort=True,
flex=peak_config["flex"],
min_distance_from_avg=peak_config["min_distance_from_avg"],
@ -784,35 +687,32 @@ class TibberPricesPeriodCalculator:
level_filter=min_level_peak,
gap_count=gap_count_peak,
)
peak_periods = calculate_periods_with_relaxation(
peak_periods, peak_relaxation = calculate_periods_with_relaxation(
all_prices,
config=peak_period_config,
enable_relaxation=enable_relaxation_peak,
min_periods=min_periods_peak,
relaxation_step_pct=relaxation_step_peak,
max_relaxation_attempts=relaxation_attempts_peak,
should_show_callback=lambda lvl: self.should_show_periods(
price_info,
reverse_sort=True,
level_override=lvl,
),
time=self.time,
config_entry=self.config_entry,
)
else:
peak_periods = {
"periods": [],
"intervals": [],
"metadata": {
"total_intervals": 0,
"total_periods": 0,
"config": {},
"relaxation": {"relaxation_active": False, "relaxation_attempted": False},
},
"metadata": {"total_intervals": 0, "total_periods": 0, "config": {}},
}
peak_relaxation = {"relaxation_active": False, "relaxation_attempted": False}
result = {
"best_price": best_periods,
"best_price_relaxation": best_relaxation,
"peak_price": peak_periods,
"peak_price_relaxation": peak_relaxation,
}
# Cache the result

View file

@ -1,631 +0,0 @@
"""
Price data management for the coordinator.
This module manages all price-related data for the Tibber Prices integration:
**User Data** (fetched directly via API):
- Home metadata (name, address, timezone)
- Account info (subscription status)
- Currency settings
- Refreshed daily (24h interval)
**Price Data** (fetched via IntervalPool):
- Quarter-hourly price intervals
- Yesterday/today/tomorrow coverage
- The IntervalPool handles actual API fetching, deduplication, and caching
- This manager coordinates the data flow and user data refresh
Data flow:
Tibber API IntervalPool PriceDataManager Coordinator Sensors
(actual fetching) (orchestration + user data)
Note: Price data is NOT cached in this module - IntervalPool is the single
source of truth. This module only caches user_data for daily refresh cycle.
"""
from __future__ import annotations
import logging
from datetime import timedelta
from typing import TYPE_CHECKING, Any
from custom_components.tibber_prices.api import (
TibberPricesApiClientAuthenticationError,
TibberPricesApiClientCommunicationError,
TibberPricesApiClientError,
)
from homeassistant.exceptions import ConfigEntryAuthFailed
from homeassistant.helpers.update_coordinator import UpdateFailed
from . import cache, helpers
if TYPE_CHECKING:
from collections.abc import Callable
from datetime import datetime
from custom_components.tibber_prices.api import TibberPricesApiClient
from custom_components.tibber_prices.interval_pool import TibberPricesIntervalPool
from .time_service import TibberPricesTimeService
_LOGGER = logging.getLogger(__name__)
# Hour when Tibber publishes tomorrow's prices (around 13:00 local time)
# Before this hour, requesting tomorrow data will always fail → wasted API call
TOMORROW_DATA_AVAILABLE_HOUR = 13
class TibberPricesPriceDataManager:
"""
Manages price and user data for the coordinator.
Responsibilities:
- User data: Fetches directly via API, validates, caches with persistence
- Price data: Coordinates with IntervalPool (which does actual API fetching)
- Cache management: Loads/stores both data types to HA persistent storage
- Update decisions: Determines when fresh data is needed
Note: Despite the name, this class does NOT do the actual price fetching.
The IntervalPool handles API calls, deduplication, and interval management.
This class orchestrates WHEN to fetch and processes the results.
"""
def __init__( # noqa: PLR0913
self,
api: TibberPricesApiClient,
store: Any,
log_prefix: str,
user_update_interval: timedelta,
time: TibberPricesTimeService,
home_id: str,
interval_pool: TibberPricesIntervalPool,
) -> None:
"""
Initialize the price data manager.
Args:
api: API client for direct requests (user data only).
store: Home Assistant storage for persistence.
log_prefix: Prefix for log messages (e.g., "[Home Name]").
user_update_interval: How often to refresh user data (default: 1 day).
time: TimeService for time operations.
home_id: Home ID this manager is responsible for.
interval_pool: IntervalPool for price data (handles actual fetching).
"""
self.api = api
self._store = store
self._log_prefix = log_prefix
self._user_update_interval = user_update_interval
self.time: TibberPricesTimeService = time
self.home_id = home_id
self._interval_pool = interval_pool
# Cached data (user data only - price data is in IntervalPool)
self._cached_user_data: dict[str, Any] | None = None
self._last_user_update: datetime | None = None
def _log(self, level: str, message: str, *args: object, **kwargs: object) -> None:
"""Log with coordinator-specific prefix."""
prefixed_message = f"{self._log_prefix} {message}"
getattr(_LOGGER, level)(prefixed_message, *args, **kwargs)
async def load_cache(self) -> None:
"""Load cached user data from storage (price data is in IntervalPool)."""
cache_data = await cache.load_cache(self._store, self._log_prefix, time=self.time)
self._cached_user_data = cache_data.user_data
self._last_user_update = cache_data.last_user_update
def should_fetch_tomorrow_data(
self,
current_price_info: list[dict[str, Any]] | None,
) -> bool:
"""
Determine if tomorrow's data should be requested from the API.
This is the key intelligence that prevents API spam:
- Tibber publishes tomorrow's prices around 13:00 each day
- Before 13:00, requesting tomorrow data will always fail wasted API call
- If we already have tomorrow data, no need to request it again
The decision logic:
1. Before 13:00 local time Don't fetch (data not available yet)
2. After 13:00 AND tomorrow data already present Don't fetch (already have it)
3. After 13:00 AND tomorrow data missing Fetch (data should be available)
Args:
current_price_info: List of price intervals from current coordinator data.
Used to check if tomorrow data already exists.
Returns:
True if tomorrow data should be requested, False otherwise.
"""
now = self.time.now()
now_local = self.time.as_local(now)
current_hour = now_local.hour
# Before TOMORROW_DATA_AVAILABLE_HOUR - tomorrow data not available yet
if current_hour < TOMORROW_DATA_AVAILABLE_HOUR:
self._log("debug", "Before %d:00 - not requesting tomorrow data", TOMORROW_DATA_AVAILABLE_HOUR)
return False
# After TOMORROW_DATA_AVAILABLE_HOUR - check if we already have tomorrow data
if current_price_info:
has_tomorrow = self.has_tomorrow_data(current_price_info)
if has_tomorrow:
self._log(
"debug", "After %d:00 but already have tomorrow data - not requesting", TOMORROW_DATA_AVAILABLE_HOUR
)
return False
self._log("debug", "After %d:00 and tomorrow data missing - will request", TOMORROW_DATA_AVAILABLE_HOUR)
return True
# No current data - request tomorrow data if after TOMORROW_DATA_AVAILABLE_HOUR
self._log(
"debug", "After %d:00 with no current data - will request tomorrow data", TOMORROW_DATA_AVAILABLE_HOUR
)
return True
async def store_cache(self, last_midnight_check: datetime | None = None) -> None:
"""Store cache data (user metadata only, price data is in IntervalPool)."""
cache_data = cache.TibberPricesCacheData(
user_data=self._cached_user_data,
last_user_update=self._last_user_update,
last_midnight_check=last_midnight_check,
)
await cache.save_cache(self._store, cache_data, self._log_prefix)
def _validate_user_data(self, user_data: dict, home_id: str) -> bool: # noqa: PLR0911
"""
Validate user data completeness.
Rejects incomplete/invalid data from API to prevent caching temporary errors.
Currency information is critical - if missing, we cannot safely calculate prices.
Args:
user_data: User data dict from API.
home_id: Home ID to validate against.
Returns:
True if data is valid and complete, False otherwise.
"""
if not user_data:
self._log("warning", "User data validation failed: Empty data")
return False
viewer = user_data.get("viewer")
if not viewer or not isinstance(viewer, dict):
self._log("warning", "User data validation failed: Missing or invalid viewer")
return False
homes = viewer.get("homes")
if not homes or not isinstance(homes, list) or len(homes) == 0:
self._log("warning", "User data validation failed: No homes found")
return False
# Find our home and validate it has required data
home_found = False
for home in homes:
if home.get("id") == home_id:
home_found = True
# Validate home has timezone (required for cursor calculation)
if not home.get("timeZone"):
self._log("warning", "User data validation failed: Home %s missing timezone", home_id)
return False
# Currency is REQUIRED - we cannot function without it
# The currency is nested in currentSubscription.priceInfo.current.currency
subscription = home.get("currentSubscription")
if not subscription:
self._log(
"warning",
"User data validation failed: Home %s has no active subscription",
home_id,
)
return False
price_info = subscription.get("priceInfo")
if not price_info:
self._log(
"warning",
"User data validation failed: Home %s subscription has no priceInfo",
home_id,
)
return False
current = price_info.get("current")
if not current:
self._log(
"warning",
"User data validation failed: Home %s priceInfo has no current data",
home_id,
)
return False
currency = current.get("currency")
if not currency:
self._log(
"warning",
"User data validation failed: Home %s has no currency",
home_id,
)
return False
break
if not home_found:
self._log("warning", "User data validation failed: Home %s not found in homes list", home_id)
return False
self._log("debug", "User data validation passed for home %s", home_id)
return True
async def update_user_data_if_needed(self, current_time: datetime) -> bool:
"""
Update user data if needed (daily check).
Only accepts complete and valid data. If API returns incomplete data
(e.g., during maintenance), keeps existing cached data and retries later.
Returns:
True if user data was updated, False otherwise
"""
if self._last_user_update is None or current_time - self._last_user_update >= self._user_update_interval:
try:
self._log("debug", "Updating user data")
user_data = await self.api.async_get_viewer_details()
# Validate before caching
if not self._validate_user_data(user_data, self.home_id):
self._log(
"warning",
"Rejecting incomplete user data from API - keeping existing cached data",
)
return False # Keep existing data, don't update timestamp
# Data is valid, cache it
self._cached_user_data = user_data
self._last_user_update = current_time
self._log("debug", "User data updated successfully")
except (
TibberPricesApiClientError,
TibberPricesApiClientCommunicationError,
) as ex:
self._log("warning", "Failed to update user data: %s", ex)
return False # Update failed
else:
return True # User data was updated
return False # No update needed
async def fetch_home_data(
self,
home_id: str,
current_time: datetime,
*,
include_tomorrow: bool = True,
) -> tuple[dict[str, Any], bool]:
"""
Fetch data for a single home via pool.
Args:
home_id: Home ID to fetch data for.
current_time: Current time for timestamp in result.
include_tomorrow: If True, request tomorrow's data too. If False,
only request up to end of today.
Returns:
Tuple of (data_dict, api_called):
- data_dict: Dictionary with timestamp, home_id, price_info, currency.
- api_called: True if API was called to fetch missing data.
"""
if not home_id:
self._log("warning", "No home ID provided - cannot fetch price data")
return (
{
"timestamp": current_time,
"home_id": "",
"price_info": [],
"currency": "EUR",
},
False, # No API call made
)
# Ensure we have user_data before fetching price data
# This is critical for timezone-aware cursor calculation
if not self._cached_user_data:
self._log("info", "User data not cached, fetching before price data")
try:
user_data = await self.api.async_get_viewer_details()
# Validate data before accepting it (especially on initial setup)
if not self._validate_user_data(user_data, self.home_id):
msg = "Received incomplete user data from API - cannot proceed with price fetching"
self._log("error", msg)
raise TibberPricesApiClientError(msg) # noqa: TRY301
self._cached_user_data = user_data
self._last_user_update = current_time
except (
TibberPricesApiClientError,
TibberPricesApiClientCommunicationError,
) as ex:
msg = f"Failed to fetch user data (required for price fetching): {ex}"
self._log("error", msg)
raise TibberPricesApiClientError(msg) from ex
# At this point, _cached_user_data is guaranteed to be not None (checked above)
if not self._cached_user_data:
msg = "User data unexpectedly None after fetch attempt"
raise TibberPricesApiClientError(msg)
# Retrieve price data via IntervalPool (single source of truth)
price_info, api_called = await self._fetch_via_pool(home_id, include_tomorrow=include_tomorrow)
# Extract currency for this home from user_data
currency = self._get_currency_for_home(home_id)
self._log(
"debug",
"Successfully fetched data for home %s (%d intervals, api_called=%s)",
home_id,
len(price_info),
api_called,
)
return (
{
"timestamp": current_time,
"home_id": home_id,
"price_info": price_info,
"currency": currency,
},
api_called,
)
async def _fetch_via_pool(
self,
home_id: str,
*,
include_tomorrow: bool = True,
) -> tuple[list[dict[str, Any]], bool]:
"""
Retrieve price data via IntervalPool.
The IntervalPool is the single source of truth for price data:
- Handles actual API calls to Tibber
- Manages deduplication and caching
- Provides intervals from day-before-yesterday to end-of-today/tomorrow
This method delegates to the Pool's get_sensor_data() which returns
all relevant intervals for sensor display.
Args:
home_id: Home ID (currently unused, Pool knows its home).
include_tomorrow: If True, request tomorrow's data too. If False,
only request up to end of today. This prevents
API spam before 13:00 when Tibber doesn't have
tomorrow data yet.
Returns:
Tuple of (intervals, api_called):
- intervals: List of price interval dicts.
- api_called: True if API was called to fetch missing data.
"""
# user_data is guaranteed by fetch_home_data(), but needed for type narrowing
if self._cached_user_data is None:
return [], False # No data, no API call
self._log(
"debug",
"Retrieving price data for home %s via interval pool (include_tomorrow=%s)",
home_id,
include_tomorrow,
)
intervals, api_called = await self._interval_pool.get_sensor_data(
api_client=self.api,
user_data=self._cached_user_data,
include_tomorrow=include_tomorrow,
)
return intervals, api_called
def _get_currency_for_home(self, home_id: str) -> str:
"""
Get currency for a specific home from cached user_data.
Note: The cached user_data is validated before storage, so if we have
cached data it should contain valid currency. This method extracts
the currency from the nested structure.
Returns:
Currency code (e.g., "EUR", "NOK", "SEK").
Raises:
TibberPricesApiClientError: If currency cannot be determined.
"""
if not self._cached_user_data:
msg = "No user data cached - cannot determine currency"
self._log("error", msg)
raise TibberPricesApiClientError(msg)
viewer = self._cached_user_data.get("viewer", {})
homes = viewer.get("homes", [])
for home in homes:
if home.get("id") == home_id:
# Extract currency from nested structure
# Use 'or {}' to handle None values (homes without active subscription)
subscription = home.get("currentSubscription") or {}
price_info = subscription.get("priceInfo") or {}
current = price_info.get("current") or {}
currency = current.get("currency")
if not currency:
# This should not happen if validation worked correctly
msg = f"Home {home_id} has no active subscription - currency unavailable"
self._log("error", msg)
raise TibberPricesApiClientError(msg)
self._log("debug", "Extracted currency %s for home %s", currency, home_id)
return currency
# Home not found in cached data - data validation should have caught this
msg = f"Home {home_id} not found in user data - data validation failed"
self._log("error", msg)
raise TibberPricesApiClientError(msg)
def _check_home_exists(self, home_id: str) -> bool:
"""
Check if a home ID exists in cached user data.
Args:
home_id: The home ID to check.
Returns:
True if home exists, False otherwise.
"""
if not self._cached_user_data:
# No user data yet - assume home exists (will be checked on next update)
return True
viewer = self._cached_user_data.get("viewer", {})
homes = viewer.get("homes", [])
return any(home.get("id") == home_id for home in homes)
async def handle_main_entry_update(
self,
current_time: datetime,
home_id: str,
transform_fn: Callable[[dict[str, Any]], dict[str, Any]],
*,
current_price_info: list[dict[str, Any]] | None = None,
) -> tuple[dict[str, Any], bool]:
"""
Handle update for main entry - fetch data for this home.
The IntervalPool is the single source of truth for price data:
- It handles API fetching, deduplication, and caching internally
- We decide WHEN to fetch tomorrow data (after 13:00, if not already present)
- This prevents API spam before 13:00 when Tibber doesn't have tomorrow data
This method:
1. Updates user data if needed (daily)
2. Determines if tomorrow data should be requested
3. Fetches price data via IntervalPool
4. Transforms result for coordinator
Args:
current_time: Current time for update decisions.
home_id: Home ID to fetch data for.
transform_fn: Function to transform raw data for coordinator.
current_price_info: Current price intervals (from coordinator.data["priceInfo"]).
Used to check if tomorrow data already exists.
Returns:
Tuple of (transformed_data, api_called):
- transformed_data: Transformed data dict for coordinator.
- api_called: True if API was called to fetch missing data.
"""
# Update user data if needed (daily check)
user_data_updated = await self.update_user_data_if_needed(current_time)
# Check if this home still exists in user data after update
# This detects when a home was removed from the Tibber account
home_exists = self._check_home_exists(home_id)
if not home_exists:
self._log("warning", "Home ID %s not found in Tibber account", home_id)
# Return a special marker in the result that coordinator can check
result = transform_fn({})
result["_home_not_found"] = True # Special marker for coordinator
return result, False # No API call made (home doesn't exist)
# Determine if we should request tomorrow data
include_tomorrow = self.should_fetch_tomorrow_data(current_price_info)
# Fetch price data via IntervalPool
self._log(
"debug",
"Fetching price data for home %s via interval pool (include_tomorrow=%s)",
home_id,
include_tomorrow,
)
raw_data, api_called = await self.fetch_home_data(home_id, current_time, include_tomorrow=include_tomorrow)
# Parse timestamps immediately after fetch
raw_data = helpers.parse_all_timestamps(raw_data, time=self.time)
# Store user data cache (price data persisted by IntervalPool)
if user_data_updated:
await self.store_cache()
# Transform for main entry
return transform_fn(raw_data), api_called
async def handle_api_error(
self,
error: Exception,
) -> None:
"""
Handle API errors - re-raise appropriate exceptions.
Note: With IntervalPool as source of truth, there's no local price cache
to fall back to. The Pool has its own persistence, so on next update
it will use its cached intervals if API is unavailable.
"""
if isinstance(error, TibberPricesApiClientAuthenticationError):
msg = "Invalid access token"
raise ConfigEntryAuthFailed(msg) from error
msg = f"Error communicating with API: {error}"
raise UpdateFailed(msg) from error
@property
def cached_user_data(self) -> dict[str, Any] | None:
"""Get cached user data."""
return self._cached_user_data
def has_tomorrow_data(self, price_info: list[dict[str, Any]]) -> bool:
"""
Check if tomorrow's price data is available.
Args:
price_info: List of price intervals from coordinator data.
Returns:
True if at least one interval from tomorrow is present.
"""
if not price_info:
return False
# Get tomorrow's date
now = self.time.now()
tomorrow = (self.time.as_local(now) + timedelta(days=1)).date()
# Check if any interval is from tomorrow
for interval in price_info:
if "startsAt" not in interval:
continue
# startsAt is already a datetime object after _transform_data()
interval_time = interval["startsAt"]
if isinstance(interval_time, str):
# Fallback: parse if still string (shouldn't happen with transformed data)
interval_time = self.time.parse_datetime(interval_time)
if interval_time and self.time.as_local(interval_time).date() == tomorrow:
return True
return False

View file

@ -1,228 +0,0 @@
"""
Repair issue management for Tibber Prices integration.
This module handles creation and cleanup of repair issues that notify users
about problems requiring attention in the Home Assistant UI.
Repair Types:
1. Tomorrow Data Missing - Warns when tomorrow's price data is unavailable after 18:00
2. Persistent Rate Limits - Warns when API rate limiting persists after multiple errors
3. Home Not Found - Warns when a home no longer exists in the Tibber account
"""
from __future__ import annotations
import logging
from typing import TYPE_CHECKING
from custom_components.tibber_prices.const import DOMAIN
from homeassistant.helpers import issue_registry as ir
if TYPE_CHECKING:
from datetime import datetime
from homeassistant.core import HomeAssistant
_LOGGER = logging.getLogger(__name__)
# Repair issue tracking thresholds
TOMORROW_DATA_WARNING_HOUR = 18 # Warn after 18:00 if tomorrow data missing
RATE_LIMIT_WARNING_THRESHOLD = 3 # Warn after 3 consecutive rate limit errors
class TibberPricesRepairManager:
"""Manage repair issues for Tibber Prices integration."""
def __init__(self, hass: HomeAssistant, entry_id: str, home_name: str) -> None:
"""
Initialize repair manager.
Args:
hass: Home Assistant instance
entry_id: Config entry ID for this home
home_name: Display name of the home (for user-friendly messages)
"""
self._hass = hass
self._entry_id = entry_id
self._home_name = home_name
# Track consecutive rate limit errors
self._rate_limit_error_count = 0
# Track if repairs are currently active
self._tomorrow_data_repair_active = False
self._rate_limit_repair_active = False
self._home_not_found_repair_active = False
async def check_tomorrow_data_availability(
self,
has_tomorrow_data: bool, # noqa: FBT001 - Clear meaning in context
current_time: datetime,
) -> None:
"""
Check if tomorrow data is available and create/clear repair as needed.
Creates repair if:
- Current hour >= 18:00 (after expected data availability)
- Tomorrow's data is missing
Clears repair if:
- Tomorrow's data is now available
Args:
has_tomorrow_data: Whether tomorrow's data is available
current_time: Current local datetime for hour check
"""
should_warn = current_time.hour >= TOMORROW_DATA_WARNING_HOUR and not has_tomorrow_data
if should_warn and not self._tomorrow_data_repair_active:
await self._create_tomorrow_data_repair()
elif not should_warn and self._tomorrow_data_repair_active:
await self._clear_tomorrow_data_repair()
async def track_rate_limit_error(self) -> None:
"""
Track rate limit error and create repair if threshold exceeded.
Increments rate limit error counter and creates repair issue
if threshold (3 consecutive errors) is reached.
"""
self._rate_limit_error_count += 1
if self._rate_limit_error_count >= RATE_LIMIT_WARNING_THRESHOLD and not self._rate_limit_repair_active:
await self._create_rate_limit_repair()
async def clear_rate_limit_tracking(self) -> None:
"""
Clear rate limit error tracking after successful API call.
Resets counter and clears any active repair issue.
"""
self._rate_limit_error_count = min(self._rate_limit_error_count, 0)
if self._rate_limit_repair_active:
await self._clear_rate_limit_repair()
async def create_home_not_found_repair(self) -> None:
"""
Create repair for home no longer found in Tibber account.
This indicates the home was deleted from the user's Tibber account
but the config entry still exists in Home Assistant.
"""
if self._home_not_found_repair_active:
return
_LOGGER.warning(
"Home '%s' not found in Tibber account - creating repair issue",
self._home_name,
)
ir.async_create_issue(
self._hass,
DOMAIN,
f"home_not_found_{self._entry_id}",
is_fixable=True,
severity=ir.IssueSeverity.ERROR,
translation_key="home_not_found",
translation_placeholders={
"home_name": self._home_name,
"entry_id": self._entry_id,
},
)
self._home_not_found_repair_active = True
async def clear_home_not_found_repair(self) -> None:
"""Clear home not found repair (home is available again or entry removed)."""
if not self._home_not_found_repair_active:
return
_LOGGER.debug("Clearing home not found repair for '%s'", self._home_name)
ir.async_delete_issue(
self._hass,
DOMAIN,
f"home_not_found_{self._entry_id}",
)
self._home_not_found_repair_active = False
async def clear_all_repairs(self) -> None:
"""
Clear all active repair issues.
Called during coordinator shutdown or entry removal.
"""
if self._tomorrow_data_repair_active:
await self._clear_tomorrow_data_repair()
if self._rate_limit_repair_active:
await self._clear_rate_limit_repair()
if self._home_not_found_repair_active:
await self.clear_home_not_found_repair()
async def _create_tomorrow_data_repair(self) -> None:
"""Create repair issue for missing tomorrow data."""
_LOGGER.warning(
"Tomorrow's price data missing after %d:00 for home '%s' - creating repair issue",
TOMORROW_DATA_WARNING_HOUR,
self._home_name,
)
ir.async_create_issue(
self._hass,
DOMAIN,
f"tomorrow_data_missing_{self._entry_id}",
is_fixable=False,
severity=ir.IssueSeverity.WARNING,
translation_key="tomorrow_data_missing",
translation_placeholders={
"home_name": self._home_name,
"warning_hour": str(TOMORROW_DATA_WARNING_HOUR),
},
)
self._tomorrow_data_repair_active = True
async def _clear_tomorrow_data_repair(self) -> None:
"""Clear tomorrow data repair issue."""
_LOGGER.debug("Tomorrow's data now available for '%s' - clearing repair issue", self._home_name)
ir.async_delete_issue(
self._hass,
DOMAIN,
f"tomorrow_data_missing_{self._entry_id}",
)
self._tomorrow_data_repair_active = False
async def _create_rate_limit_repair(self) -> None:
"""Create repair issue for persistent rate limiting."""
_LOGGER.warning(
"Persistent API rate limiting detected for home '%s' (%d consecutive errors) - creating repair issue",
self._home_name,
self._rate_limit_error_count,
)
ir.async_create_issue(
self._hass,
DOMAIN,
f"rate_limit_exceeded_{self._entry_id}",
is_fixable=False,
severity=ir.IssueSeverity.WARNING,
translation_key="rate_limit_exceeded",
translation_placeholders={
"home_name": self._home_name,
"error_count": str(self._rate_limit_error_count),
},
)
self._rate_limit_repair_active = True
async def _clear_rate_limit_repair(self) -> None:
"""Clear rate limit repair issue."""
_LOGGER.debug("Rate limiting resolved for '%s' - clearing repair issue", self._home_name)
ir.async_delete_issue(
self._hass,
DOMAIN,
f"rate_limit_exceeded_{self._entry_id}",
)
self._rate_limit_repair_active = False

View file

@ -1,828 +0,0 @@
"""
TimeService - Centralized time management for Tibber Prices integration.
This service provides:
1. Single source of truth for current time
2. Timezone-aware operations (respects HA user timezone)
3. Domain-specific datetime methods (intervals, boundaries, horizons)
4. Time-travel capability (inject simulated time for testing)
All datetime operations MUST go through TimeService to ensure:
- Consistent time across update cycles
- Proper timezone handling (local time, not UTC)
- Testability (mock time in one place)
- Future time-travel feature support
TIMER ARCHITECTURE:
This integration uses three distinct timer mechanisms:
1. **Timer #1: API Polling (DataUpdateCoordinator)**
- Runs every 15 minutes at a RANDOM offset (e.g., 10:04:37, 10:19:37, 10:34:37)
- Offset determined by when last API call completed
- Tracked via _last_coordinator_update for next poll prediction
- NO tolerance needed - offset variation is INTENTIONAL
- Purpose: Spread API load, avoid thundering herd problem
2. **Timer #2: Entity Updates (quarter-hour boundaries)**
- Must trigger at EXACT boundaries (00, 15, 30, 45 minutes)
- Uses _BOUNDARY_TOLERANCE_SECONDS for HA scheduling jitter correction
- Scheduled via async_track_utc_time_change(minute=[0,15,30,45], second=0)
- If HA triggers at 15:00:01 round to 15:00:00 (within ±2s tolerance)
- Purpose: Entity state updates reflect correct quarter-hour interval
3. **Timer #3: Timing Sensors (30-second boundaries)**
- Must trigger at EXACT boundaries (0, 30 seconds)
- Uses _BOUNDARY_TOLERANCE_SECONDS for HA scheduling jitter correction
- Scheduled via async_track_utc_time_change(second=[0,30])
- Purpose: Update countdown/time-to sensors
CRITICAL: The tolerance is ONLY for Timer #2 and #3 to correct HA's
scheduling delays. It is NOT used for Timer #1's offset tracking.
"""
from __future__ import annotations
import math
from datetime import datetime, timedelta
from typing import TYPE_CHECKING
from homeassistant.util import dt as dt_util
if TYPE_CHECKING:
from datetime import date
# =============================================================================
# CRITICAL: This is the ONLY module allowed to import dt_util for operations!
# =============================================================================
#
# Other modules may import dt_util ONLY in these cases:
# 1. api/client.py - Rate limiting (non-critical, cosmetic)
# 2. entity_utils/icons.py - Icon updates (cosmetic, independent)
#
# All business logic MUST use TimeService instead.
# =============================================================================
# Constants (private - use TimeService methods instead)
_DEFAULT_INTERVAL_MINUTES = 15 # Tibber uses 15-minute intervals
_INTERVALS_PER_HOUR = 60 // _DEFAULT_INTERVAL_MINUTES # 4
_INTERVALS_PER_DAY = 24 * _INTERVALS_PER_HOUR # 96
# Rounding tolerance for boundary detection (±2 seconds)
# This handles Home Assistant's scheduling jitter for Timer #2 (entity updates)
# and Timer #3 (timing sensors). When HA schedules a callback for exactly
# 15:00:00 but actually triggers it at 15:00:01, this tolerance ensures we
# still recognize it as the 15:00:00 boundary.
#
# NOT used for Timer #1 (API polling), which intentionally runs at random
# offsets determined by last API call completion time.
_BOUNDARY_TOLERANCE_SECONDS = 2
class TibberPricesTimeService:
"""
Centralized time service for Tibber Prices integration.
Provides timezone-aware datetime operations with consistent time context.
All times are in user's Home Assistant local timezone.
Features:
- Single source of truth for "now" per update cycle
- Domain-specific methods (intervals, periods, boundaries)
- Time-travel support (inject simulated time)
- Timezone-safe (all operations respect HA user timezone)
Usage:
# Create service with current time
time_service = TimeService()
# Get consistent "now" throughout update cycle
now = time_service.now()
# Domain-specific operations
current_interval_start = time_service.get_current_interval_start()
next_interval = time_service.get_interval_offset_time(1)
midnight = time_service.get_local_midnight()
"""
def __init__(self, reference_time: datetime | None = None) -> None:
"""
Initialize TimeService with reference time.
Args:
reference_time: Optional fixed time for this context.
If None, uses actual current time.
For time-travel: pass simulated time here.
"""
self._reference_time = reference_time or dt_util.now()
# =========================================================================
# Low-Level API: Direct dt_util wrappers
# =========================================================================
def now(self) -> datetime:
"""
Get current reference time in user's local timezone.
Returns same value throughout the lifetime of this TimeService instance.
This ensures consistent time across all calculations in an update cycle.
Returns:
Timezone-aware datetime in user's HA local timezone.
"""
return self._reference_time
def get_rounded_now(self) -> datetime:
"""
Get current reference time rounded to nearest 15-minute boundary.
Convenience method that combines now() + round_to_nearest_quarter().
Use this when you need the current interval timestamp for calculations.
Returns:
Current reference time rounded to :00, :15, :30, or :45
Examples:
If now is 14:59:58 returns 15:00:00
If now is 14:59:30 returns 14:45:00
If now is 15:00:01 returns 15:00:00
"""
return self.round_to_nearest_quarter()
def as_local(self, dt: datetime) -> datetime:
"""
Convert datetime to user's local timezone.
Args:
dt: Timezone-aware datetime (any timezone).
Returns:
Same moment in time, converted to user's local timezone.
"""
return dt_util.as_local(dt)
def parse_datetime(self, dt_str: str) -> datetime | None:
"""
Parse ISO 8601 datetime string.
Args:
dt_str: ISO 8601 formatted string (e.g., "2025-11-19T13:00:00+00:00").
Returns:
Timezone-aware datetime, or None if parsing fails.
"""
return dt_util.parse_datetime(dt_str)
def parse_and_localize(self, dt_str: str) -> datetime | None:
"""
Parse ISO string and convert to user's local timezone.
Combines parse_datetime() + as_local() in one call.
Use this for API timestamps that need immediate localization.
Args:
dt_str: ISO 8601 formatted string (e.g., "2025-11-19T13:00:00+00:00").
Returns:
Timezone-aware datetime in user's local timezone, or None if parsing fails.
"""
parsed = self.parse_datetime(dt_str)
return self.as_local(parsed) if parsed else None
def start_of_local_day(self, dt: datetime | None = None) -> datetime:
"""
Get midnight (00:00) of the given datetime in user's local timezone.
Args:
dt: Reference datetime. If None, uses reference_time.
Returns:
Midnight (start of day) in user's local timezone.
"""
target = dt if dt is not None else self._reference_time
return dt_util.start_of_local_day(target)
# =========================================================================
# High-Level API: Domain-Specific Methods
# =========================================================================
# -------------------------------------------------------------------------
# Interval Data Extraction
# -------------------------------------------------------------------------
def get_interval_time(self, interval: dict) -> datetime | None:
"""
Extract and parse interval timestamp from API data.
Handles common pattern: parse "startsAt" + convert to local timezone.
Replaces repeated parse_datetime() + as_local() pattern.
Args:
interval: Price interval dict with "startsAt" field (ISO string or datetime object)
Returns:
Localized datetime or None if parsing/conversion fails
"""
starts_at = interval.get("startsAt")
if not starts_at:
return None
# If already a datetime object (parsed from cache), return as-is
if isinstance(starts_at, datetime):
return starts_at
# Otherwise parse the string
return self.parse_and_localize(starts_at)
# -------------------------------------------------------------------------
# Time Comparison Helpers
# -------------------------------------------------------------------------
def is_in_past(self, dt: datetime) -> bool:
"""
Check if datetime is before reference time (now).
Args:
dt: Datetime to check
Returns:
True if dt < now()
"""
return dt < self.now()
def is_in_future(self, dt: datetime) -> bool:
"""
Check if datetime is after or equal to reference time (now).
Args:
dt: Datetime to check
Returns:
True if dt >= now()
"""
return dt >= self.now()
def is_current_interval(self, start: datetime, end: datetime) -> bool:
"""
Check if reference time (now) falls within interval [start, end).
Args:
start: Interval start time (inclusive)
end: Interval end time (exclusive)
Returns:
True if start <= now() < end
"""
now = self.now()
return start <= now < end
def is_in_day(self, dt: datetime, day: str) -> bool:
"""
Check if datetime falls within specified calendar day.
Args:
dt: Datetime to check (should be localized)
day: "yesterday", "today", or "tomorrow"
Returns:
True if dt is within day boundaries
"""
start, end = self.get_day_boundaries(day)
return start <= dt < end
# -------------------------------------------------------------------------
# Duration Calculations
# -------------------------------------------------------------------------
def get_hours_until(self, future_time: datetime) -> float:
"""
Calculate hours from reference time (now) until future_time.
Args:
future_time: Future datetime
Returns:
Hours (can be negative if in past, decimal for partial hours)
"""
delta = future_time - self.now()
return delta.total_seconds() / 3600
def get_local_date(self, offset_days: int = 0) -> date:
"""
Get date for day at offset from reference date.
Convenience method to replace repeated time.now().date() or
time.get_local_midnight(n).date() patterns.
Args:
offset_days: Days to offset.
0 = today, 1 = tomorrow, -1 = yesterday, etc.
Returns:
Date object in user's local timezone.
Examples:
get_local_date() today's date
get_local_date(1) tomorrow's date
get_local_date(-1) yesterday's date
"""
target_datetime = self._reference_time + timedelta(days=offset_days)
return target_datetime.date()
def is_time_in_period(self, start: datetime, end: datetime, check_time: datetime | None = None) -> bool:
"""
Check if time falls within period [start, end).
Args:
start: Period start time (inclusive)
end: Period end time (exclusive)
check_time: Time to check. If None, uses reference time (now).
Returns:
True if start <= check_time < end
Examples:
# Check if now is in period:
is_time_in_period(period_start, period_end)
# Check if specific time is in period:
is_time_in_period(window_start, window_end, some_timestamp)
"""
t = check_time if check_time is not None else self.now()
return start <= t < end
def is_time_within_horizon(self, target_time: datetime, hours: int) -> bool:
"""
Check if target time is in future within specified hour horizon.
Combines two common checks:
1. Is target_time in the future? (target_time > now)
2. Is target_time within N hours? (target_time <= now + N hours)
Args:
target_time: Time to check
hours: Lookahead horizon in hours
Returns:
True if now < target_time <= now + hours
Examples:
# Check if period starts within next 6 hours:
is_time_within_horizon(period_start, hours=6)
# Check if event happens within next 24 hours:
is_time_within_horizon(event_time, hours=24)
"""
now = self.now()
horizon = now + timedelta(hours=hours)
return now < target_time <= horizon
def hours_since(self, past_time: datetime) -> float:
"""
Calculate hours from past_time until reference time (now).
Args:
past_time: Past datetime
Returns:
Hours (can be negative if in future, decimal for partial hours)
"""
delta = self.now() - past_time
return delta.total_seconds() / 3600
def minutes_until(self, future_time: datetime) -> float:
"""
Calculate minutes from reference time (now) until future_time.
Args:
future_time: Future datetime
Returns:
Minutes (can be negative if in past, decimal for partial minutes)
"""
delta = future_time - self.now()
return delta.total_seconds() / 60
def minutes_until_rounded(self, future_time: datetime | str) -> int:
"""
Calculate ROUNDED minutes from reference time (now) until future_time.
Uses standard rounding (0.5 rounds up) to match Home Assistant frontend
relative time display. This ensures sensor values match what users see
in the UI ("in X minutes").
Args:
future_time: Future datetime or ISO string to parse
Returns:
Rounded minutes (negative if in past)
Examples:
44.2 minutes 44
44.5 minutes 45 (rounds up, like HA frontend)
44.7 minutes 45
"""
# Parse string if needed
if isinstance(future_time, str):
parsed = self.parse_and_localize(future_time)
if not parsed:
return 0
future_time = parsed
delta = future_time - self.now()
seconds = delta.total_seconds()
# Standard rounding: 0.5 rounds up (matches HA frontend behavior)
# Using math.floor + 0.5 instead of Python's round() which uses banker's rounding
return math.floor(seconds / 60 + 0.5)
# -------------------------------------------------------------------------
# Interval Operations (15-minute grid)
# -------------------------------------------------------------------------
def get_interval_duration(self) -> timedelta:
"""
Get duration of one interval.
Returns:
Timedelta representing interval length (15 minutes for Tibber).
"""
return timedelta(minutes=_DEFAULT_INTERVAL_MINUTES)
def minutes_to_intervals(self, minutes: int) -> int:
"""
Convert minutes to number of intervals.
Args:
minutes: Number of minutes to convert.
Returns:
Number of intervals (rounded down).
Examples:
15 minutes 1 interval
30 minutes 2 intervals
45 minutes 3 intervals
60 minutes 4 intervals
"""
return minutes // _DEFAULT_INTERVAL_MINUTES
def round_to_nearest_quarter(self, dt: datetime | None = None) -> datetime:
"""
Round datetime to nearest 15-minute boundary with smart tolerance.
Handles HA scheduling jitter: if within ±2 seconds of boundary,
round to that boundary. Otherwise, floor to current interval.
Args:
dt: Datetime to round. If None, uses reference_time.
Returns:
Datetime rounded to nearest quarter-hour boundary.
Examples:
14:59:58 15:00:00 (within 2s of boundary)
14:59:30 14:45:00 (not within 2s, stay in current)
15:00:01 15:00:00 (within 2s of boundary)
"""
target = dt if dt is not None else self._reference_time
# Calculate total seconds in day
total_seconds = target.hour * 3600 + target.minute * 60 + target.second + target.microsecond / 1_000_000
# Find current interval boundaries
interval_index = int(total_seconds // (_DEFAULT_INTERVAL_MINUTES * 60))
interval_start_seconds = interval_index * _DEFAULT_INTERVAL_MINUTES * 60
next_interval_index = (interval_index + 1) % _INTERVALS_PER_DAY
next_interval_start_seconds = next_interval_index * _DEFAULT_INTERVAL_MINUTES * 60
# Distance to boundaries
distance_to_current = total_seconds - interval_start_seconds
if next_interval_index == 0: # Midnight wrap
distance_to_next = (24 * 3600) - total_seconds
else:
distance_to_next = next_interval_start_seconds - total_seconds
# Apply tolerance: if within 2 seconds of a boundary, round to it
if distance_to_current <= _BOUNDARY_TOLERANCE_SECONDS:
# Near current interval start → use it
rounded_seconds = interval_start_seconds
elif distance_to_next <= _BOUNDARY_TOLERANCE_SECONDS:
# Near next interval start → use it
# CRITICAL: If rounding to next interval and it wraps to midnight (index 0),
# we need to increment to next day, not stay on same day!
if next_interval_index == 0:
# Rounding to midnight of NEXT day
return (target + timedelta(days=1)).replace(hour=0, minute=0, second=0, microsecond=0)
rounded_seconds = next_interval_start_seconds
else:
# Not near any boundary → floor to current interval
rounded_seconds = interval_start_seconds
# Build rounded datetime (no midnight wrap needed here - handled above)
hours = int(rounded_seconds // 3600)
minutes = int((rounded_seconds % 3600) // 60)
return target.replace(hour=hours, minute=minutes, second=0, microsecond=0)
def get_current_interval_start(self) -> datetime:
"""
Get start time of current 15-minute interval.
Returns:
Datetime at start of current interval (rounded down).
Example:
Reference time 14:37:23 returns 14:30:00
"""
return self.round_to_nearest_quarter(self._reference_time)
def get_next_interval_start(self) -> datetime:
"""
Get start time of next 15-minute interval.
Returns:
Datetime at start of next interval.
Example:
Reference time 14:37:23 returns 14:45:00
"""
return self.get_interval_offset_time(1)
def get_interval_offset_time(self, offset: int = 0) -> datetime:
"""
Get start time of interval at offset from current.
Args:
offset: Number of intervals to offset.
0 = current, 1 = next, -1 = previous, etc.
Returns:
Datetime at start of target interval.
Examples:
offset=0 current interval (14:30:00)
offset=1 next interval (14:45:00)
offset=-1 previous interval (14:15:00)
"""
current_start = self.get_current_interval_start()
delta = timedelta(minutes=_DEFAULT_INTERVAL_MINUTES * offset)
return current_start + delta
# -------------------------------------------------------------------------
# Day Boundaries (midnight-to-midnight windows)
# -------------------------------------------------------------------------
def get_local_midnight(self, offset_days: int = 0) -> datetime:
"""
Get midnight (00:00) for day at offset from reference date.
Args:
offset_days: Days to offset.
0 = today, 1 = tomorrow, -1 = yesterday, etc.
Returns:
Midnight (start of day) in user's local timezone.
Examples:
offset_days=0 today 00:00
offset_days=1 tomorrow 00:00
offset_days=-1 yesterday 00:00
"""
target_date = self._reference_time.date() + timedelta(days=offset_days)
target_datetime = datetime.combine(target_date, datetime.min.time())
return dt_util.as_local(target_datetime)
def get_day_boundaries(self, day: str = "today") -> tuple[datetime, datetime]:
"""
Get start and end times for a day (midnight to midnight).
Args:
day: Day identifier ("day_before_yesterday", "yesterday", "today", "tomorrow").
Returns:
Tuple of (start_time, end_time) for the day.
start_time: midnight (00:00:00) of that day
end_time: midnight (00:00:00) of next day (exclusive boundary)
Examples:
day="today" (today 00:00, tomorrow 00:00)
day="yesterday" (yesterday 00:00, today 00:00)
"""
day_map = {
"day_before_yesterday": -2,
"yesterday": -1,
"today": 0,
"tomorrow": 1,
}
if day not in day_map:
msg = f"Invalid day: {day}. Must be one of {list(day_map.keys())}"
raise ValueError(msg)
offset = day_map[day]
start = self.get_local_midnight(offset)
end = self.get_local_midnight(offset + 1) # Next day's midnight
return start, end
def get_expected_intervals_for_day(self, day_date: date | None = None) -> int:
"""
Calculate expected number of 15-minute intervals for a day.
Handles DST transitions:
- Normal day: 96 intervals (24 hours * 4)
- Spring forward (lose 1 hour): 92 intervals (23 hours * 4)
- Fall back (gain 1 hour): 100 intervals (25 hours * 4)
Args:
day_date: Date to check. If None, uses reference date.
Returns:
Expected number of 15-minute intervals for that day.
"""
target_date = day_date if day_date is not None else self._reference_time.date()
# Get midnight of target day and next day in local timezone
#
# IMPORTANT: We cannot use dt_util.start_of_local_day() here due to TWO issues:
#
# Issue 1 - pytz LMT Bug:
# dt_util.start_of_local_day() uses: datetime.combine(date, time(), tzinfo=tz)
# With pytz, this triggers the "Local Mean Time" bug - using historical timezone
# offsets from before standard timezones were established (e.g., +00:53 for Berlin
# instead of +01:00/+02:00). Both timestamps get the same wrong offset, making
# duration calculations incorrect for DST transitions.
#
# Issue 2 - Python datetime Subtraction Ignores Timezone Offsets:
# Even with correct offsets (e.g., via zoneinfo):
# start = 2025-03-30 00:00+01:00 (= 2025-03-29 23:00 UTC)
# end = 2025-03-31 00:00+02:00 (= 2025-03-30 22:00 UTC)
# end - start = 1 day = 24 hours (WRONG!)
#
# Python's datetime subtraction uses naive date/time difference, ignoring that
# timezone offsets changed between the two timestamps. The real UTC duration is
# 23 hours (Spring Forward) or 25 hours (Fall Back).
#
# Solution:
# 1. Use timezone.localize() (pytz) or replace(tzinfo=tz) (zoneinfo) to get
# correct timezone-aware datetimes with proper offsets
# 2. Convert to UTC before calculating duration to account for offset changes
#
# This ensures DST transitions are correctly handled:
# - Spring Forward: 23 hours (92 intervals)
# - Fall Back: 25 hours (100 intervals)
# - Normal day: 24 hours (96 intervals)
#
tz = self._reference_time.tzinfo # Get timezone from reference time
if tz is None:
# Should never happen - dt_util.now() always returns timezone-aware datetime
msg = "Reference time has no timezone information"
raise ValueError(msg)
# Create naive datetimes for midnight of target and next day
start_naive = datetime.combine(target_date, datetime.min.time())
next_day = target_date + timedelta(days=1)
end_naive = datetime.combine(next_day, datetime.min.time())
# Localize to get correct DST offset for each date
if hasattr(tz, "localize"):
# pytz timezone - use localize() to handle DST correctly
# Type checker doesn't understand hasattr runtime check, but this is safe
start_midnight_local = tz.localize(start_naive) # type: ignore[attr-defined]
end_midnight_local = tz.localize(end_naive) # type: ignore[attr-defined]
else:
# zoneinfo or other timezone - can use replace directly
start_midnight_local = start_naive.replace(tzinfo=tz)
end_midnight_local = end_naive.replace(tzinfo=tz)
# Calculate actual duration via UTC to handle timezone offset changes correctly
# Direct subtraction (end - start) would ignore DST offset changes and always
# return 24 hours, even on Spring Forward (23h) or Fall Back (25h) days
start_utc = start_midnight_local.astimezone(dt_util.UTC)
end_utc = end_midnight_local.astimezone(dt_util.UTC)
duration = end_utc - start_utc
hours = duration.total_seconds() / 3600
# Convert to intervals (4 per hour for 15-minute intervals)
return int(hours * _INTERVALS_PER_HOUR)
# -------------------------------------------------------------------------
# Time Windows (relative to current interval)
# -------------------------------------------------------------------------
def get_trailing_window(self, hours: int = 24) -> tuple[datetime, datetime]:
"""
Get trailing time window ending at current interval.
Args:
hours: Window size in hours (default 24).
Returns:
Tuple of (start_time, end_time) for trailing window.
start_time: current interval - hours
end_time: current interval start (exclusive)
Example:
Current interval: 14:30
hours=24 (yesterday 14:30, today 14:30)
"""
end = self.get_current_interval_start()
start = end - timedelta(hours=hours)
return start, end
def get_leading_window(self, hours: int = 24) -> tuple[datetime, datetime]:
"""
Get leading time window starting at current interval.
Args:
hours: Window size in hours (default 24).
Returns:
Tuple of (start_time, end_time) for leading window.
start_time: current interval start
end_time: current interval + hours (exclusive)
Example:
Current interval: 14:30
hours=24 (today 14:30, tomorrow 14:30)
"""
start = self.get_current_interval_start()
end = start + timedelta(hours=hours)
return start, end
def get_next_n_hours_window(self, hours: int) -> tuple[datetime, datetime]:
"""
Get window for next N hours starting from NEXT interval.
Args:
hours: Window size in hours.
Returns:
Tuple of (start_time, end_time).
start_time: next interval start
end_time: next interval start + hours (exclusive)
Example:
Current interval: 14:30
hours=3 (14:45, 17:45)
"""
start = self.get_interval_offset_time(1) # Next interval
end = start + timedelta(hours=hours)
return start, end
# -------------------------------------------------------------------------
# Time-Travel Support
# -------------------------------------------------------------------------
def with_reference_time(self, new_time: datetime) -> TibberPricesTimeService:
"""
Create new TibberPricesTimeService with different reference time.
Used for time-travel testing: inject simulated "now".
Args:
new_time: New reference time.
Returns:
New TibberPricesTimeService instance with updated reference time.
Example:
# Simulate being at 14:30 on 2025-11-19
simulated_time = datetime(2025, 11, 19, 14, 30)
future_service = time_service.with_reference_time(simulated_time)
"""
return TibberPricesTimeService(reference_time=new_time)

View file

@ -1,20 +1,7 @@
{
"apexcharts": {
"title_rating_level": "Preisphasen Tagesverlauf",
"title_level": "Preisniveau",
"hourly_suffix": "(Ø stündlich)",
"best_price_period_name": "Bestpreis-Zeitraum",
"peak_price_period_name": "Spitzenpreis-Zeitraum",
"notification": {
"metadata_sensor_unavailable": {
"title": "Tibber Prices: ApexCharts YAML mit eingeschränkter Funktionalität generiert",
"message": "Du hast gerade eine ApexCharts-Card-Konfiguration über die Entwicklerwerkzeuge generiert. Der Chart-Metadaten-Sensor ist aktuell deaktiviert, daher zeigt das generierte YAML nur **Basisfunktionalität** (Auto-Skalierung, fester Gradient bei 50%).\n\n**Für volle Funktionalität** (optimierte Skalierung, dynamische Verlaufsfarben):\n1. [Tibber Prices Integration öffnen](https://my.home-assistant.io/redirect/integration/?domain=tibber_prices)\n2. Aktiviere den 'Chart Metadata' Sensor\n3. **Generiere das YAML erneut** über die Entwicklerwerkzeuge\n4. **Ersetze den alten YAML-Code** in deinem Dashboard durch die neue Version\n\n⚠ Nur den Sensor zu aktivieren reicht nicht - du musst das YAML neu generieren und ersetzen!"
},
"missing_cards": {
"title": "Tibber Prices: ApexCharts YAML kann nicht verwendet werden",
"message": "Du hast gerade eine ApexCharts-Card-Konfiguration über die Entwicklerwerkzeuge generiert, aber das generierte YAML **funktioniert nicht**, weil erforderliche Custom Cards fehlen.\n\n**Fehlende Cards:**\n{cards}\n\n**Um das generierte YAML zu nutzen:**\n1. Klicke auf die obigen Links, um die fehlenden Cards über HACS zu installieren\n2. Starte Home Assistant neu (manchmal erforderlich)\n3. **Generiere das YAML erneut** über die Entwicklerwerkzeuge\n4. Füge das YAML zu deinem Dashboard hinzu\n\n⚠ Der aktuelle YAML-Code funktioniert nicht, bis alle Cards installiert sind!"
}
}
"title_level": "Preisniveau"
},
"sensor": {
"current_interval_price": {
@ -22,7 +9,7 @@
"long_description": "Zeigt den aktuellen Preis pro kWh von deinem Tibber-Abonnement an",
"usage_tips": "Nutze dies, um Preise zu verfolgen oder Automatisierungen zu erstellen, die bei günstigem Strom ausgeführt werden"
},
"current_interval_price_base": {
"current_interval_price_major": {
"description": "Aktueller Strompreis in Hauptwährung (EUR/kWh, NOK/kWh, etc.) für Energie-Dashboard",
"long_description": "Zeigt den aktuellen Preis pro kWh in Hauptwährungseinheiten an (z.B. EUR/kWh statt ct/kWh, NOK/kWh statt øre/kWh). Dieser Sensor ist speziell für die Verwendung mit dem Energie-Dashboard von Home Assistant konzipiert, das Preise in Standard-Währungseinheiten benötigt.",
"usage_tips": "Verwende diesen Sensor beim Konfigurieren des Energie-Dashboards unter Einstellungen → Dashboards → Energie. Wähle diesen Sensor als 'Entität mit dem aktuellen Preis' aus, um deine Energiekosten automatisch zu berechnen. Das Energie-Dashboard multipliziert deinen Energieverbrauch (kWh) mit diesem Preis, um die Gesamtkosten anzuzeigen."
@ -58,9 +45,9 @@
"usage_tips": "Nutze dies, um den Betrieb von Geräten während Spitzenpreiszeiten zu vermeiden"
},
"average_price_today": {
"description": "Der typische Strompreis für heute pro kWh (konfigurierbares Anzeigeformat)",
"long_description": "Zeigt den typischen Preis pro kWh für heute. **Standardmäßig zeigt der Status den Median** (resistent gegen extreme Preisspitzen, zeigt was du generell erwarten kannst). Du kannst dies in den Integrationsoptionen ändern, um stattdessen das arithmetische Mittel anzuzeigen. Der alternative Wert ist immer als Attribut `price_mean` oder `price_median` für Automatisierungen verfügbar.",
"usage_tips": "Nutze den Status-Wert für die Anzeige. Für exakte Kostenberechnungen in Automatisierungen nutze: {{ state_attr('sensor.average_price_today', 'price_mean') }}"
"description": "Der durchschnittliche Strompreis für heute pro kWh",
"long_description": "Zeigt den durchschnittlichen Preis pro kWh für den aktuellen Tag von deinem Tibber-Abonnement an",
"usage_tips": "Nutze dies als Grundlage für den Vergleich mit aktuellen Preisen"
},
"lowest_price_tomorrow": {
"description": "Der niedrigste Strompreis für morgen pro kWh",
@ -73,9 +60,9 @@
"usage_tips": "Nutze dies, um den Betrieb von Geräten während der teuersten Stunden morgen zu vermeiden. Plane nicht-essentielle Lasten außerhalb dieser Spitzenpreiszeiten."
},
"average_price_tomorrow": {
"description": "Der typische Strompreis für morgen pro kWh (konfigurierbares Anzeigeformat)",
"long_description": "Zeigt den typischen Preis pro kWh für morgen. **Standardmäßig zeigt der Status den Median** (resistent gegen extreme Preisspitzen). Du kannst dies in den Integrationsoptionen ändern, um stattdessen das arithmetische Mittel anzuzeigen. Der alternative Wert ist als Attribut verfügbar. Dieser Sensor wird nicht verfügbar, bis die Preise für morgen von Tibber veröffentlicht werden (typischerweise zwischen 13:00 und 14:00 Uhr MEZ).",
"usage_tips": "Nutze den Status-Wert für Anzeige und schnelle Vergleiche. Für Automatisierungen, die exakte Kostenberechnungen benötigen, nutze das Attribut `price_mean`: {{ state_attr('sensor.average_price_tomorrow', 'price_mean') }}"
"description": "Der durchschnittliche Strompreis für morgen pro kWh",
"long_description": "Zeigt den durchschnittlichen Preis pro kWh für den morgigen Tag von deinem Tibber-Abonnement an. Dieser Sensor wird nicht verfügbar, bis die Preise für morgen von Tibber veröffentlicht werden (typischerweise zwischen 13:00 und 14:00 Uhr MEZ).",
"usage_tips": "Nutze dies als Grundlinie für den Vergleich mit den morgigen Preisen und zur Verbrauchsplanung. Vergleiche mit dem heutigen Durchschnitt, um zu sehen, ob morgen insgesamt teurer oder günstiger wird."
},
"yesterday_price_level": {
"description": "Aggregiertes Preisniveau für gestern",
@ -108,14 +95,14 @@
"usage_tips": "Nutze dies, um den morgigen Energieverbrauch basierend auf deinen persönlichen Preisschwellenwerten zu planen. Vergleiche mit heute, um zu entscheiden, ob du den Verbrauch auf morgen verschieben oder heute nutzen solltest."
},
"trailing_price_average": {
"description": "Der typische Strompreis der letzten 24 Stunden pro kWh (konfigurierbares Anzeigeformat)",
"long_description": "Zeigt den typischen Preis pro kWh der letzten 24 Stunden. **Standardmäßig zeigt der Status den Median** (resistent gegen extreme Spitzen, zeigt welches Preisniveau typisch war). Du kannst dies in den Integrationsoptionen ändern, um stattdessen das arithmetische Mittel anzuzeigen. Der alternative Wert ist als Attribut verfügbar. Wird alle 15 Minuten aktualisiert.",
"usage_tips": "Nutze den Status-Wert, um das typische aktuelle Preisniveau zu sehen. Für Kostenberechnungen nutze: {{ state_attr('sensor.trailing_price_average', 'price_mean') }}"
"description": "Der durchschnittliche Strompreis für die letzten 24 Stunden pro kWh",
"long_description": "Zeigt den durchschnittlichen Preis pro kWh berechnet aus den letzten 24 Stunden (nachlaufender Durchschnitt) von deinem Tibber-Abonnement an. Dies bietet einen gleitenden Durchschnitt, der alle 15 Minuten basierend auf historischen Daten aktualisiert wird.",
"usage_tips": "Nutze dies, um aktuelle Preise mit den jüngsten Trends zu vergleichen. Ein aktueller Preis deutlich über diesem Durchschnitt kann ein guter Zeitpunkt sein, um den Verbrauch zu reduzieren."
},
"leading_price_average": {
"description": "Der typische Strompreis für die nächsten 24 Stunden pro kWh (konfigurierbares Anzeigeformat)",
"long_description": "Zeigt den typischen Preis pro kWh für die nächsten 24 Stunden. **Standardmäßig zeigt der Status den Median** (resistent gegen extreme Spitzen, zeigt welches Preisniveau zu erwarten ist). Du kannst dies in den Integrationsoptionen ändern, um stattdessen das arithmetische Mittel anzuzeigen. Der alternative Wert ist als Attribut verfügbar.",
"usage_tips": "Nutze den Status-Wert, um das typische kommende Preisniveau zu sehen. Für Kostenberechnungen nutze: {{ state_attr('sensor.leading_price_average', 'price_mean') }}"
"description": "Der durchschnittliche Strompreis für die nächsten 24 Stunden pro kWh",
"long_description": "Zeigt den durchschnittlichen Preis pro kWh berechnet aus den nächsten 24 Stunden (vorlaufender Durchschnitt) von deinem Tibber-Abonnement an. Dies bietet einen vorausschauenden Durchschnitt basierend auf verfügbaren Prognosedaten.",
"usage_tips": "Nutze dies zur Energieverbrauchsplanung. Wenn der aktuelle Preis unter dem vorlaufenden Durchschnitt liegt, kann es ein guter Zeitpunkt sein, um energieintensive Geräte zu betreiben."
},
"trailing_price_min": {
"description": "Der niedrigste Strompreis für die letzten 24 Stunden pro kWh",
@ -289,32 +276,32 @@
},
"data_timestamp": {
"description": "Zeitstempel des letzten verfügbaren Preisintervalls",
"long_description": "Zeigt den Zeitstempel des letzten verfügbaren Preisdatenintervalls von deinem Tibber-Abonnement"
"long_description": "Zeigt den Zeitstempel des letzten verfügbaren Preisdatenintervalls von Ihrem Tibber-Abonnement"
},
"today_volatility": {
"description": "Wie stark sich die Strompreise heute verändern",
"long_description": "Zeigt, ob die heutigen Preise stabil bleiben oder stark schwanken. Niedrige Volatilität bedeutet recht konstante Preise Timing ist kaum wichtig. Hohe Volatilität bedeutet spürbare Preisunterschiede über den Tag gute Chance, den Verbrauch auf günstigere Zeiten zu verschieben. `price_coefficient_variation_%` zeigt den Prozentwert, `price_spread` die absolute Preisspanne.",
"usage_tips": "Nutze dies, um zu entscheiden, ob Optimierung sich lohnt. Bei niedriger Volatilität kannst du Geräte jederzeit laufen lassen. Bei hoher Volatilität sparst du spürbar, wenn du Best-Price-Perioden nutzt."
"description": "Preisvolatilitätsklassifizierung für heute",
"long_description": "Zeigt, wie stark die Strompreise im Laufe des heutigen Tages variieren, basierend auf der Spannweite (Differenz zwischen höchstem und niedrigstem Preis). Klassifizierung: NIEDRIG = Spannweite < 5ct, MODERAT = 5-15ct, HOCH = 15-30ct, SEHR HOCH = >30ct.",
"usage_tips": "Verwenden Sie dies, um zu entscheiden, ob preisbasierte Optimierung lohnenswert ist. Zum Beispiel lohnt sich bei einer Balkonbatterie mit 15% Effizienzverlusten die Optimierung nur, wenn die Volatilität mindestens MODERAT ist. Erstellen Sie Automatisierungen, die die Volatilität prüfen, bevor Lade-/Entladezyklen geplant werden."
},
"tomorrow_volatility": {
"description": "Wie stark sich die Strompreise morgen verändern werden",
"long_description": "Zeigt, ob die Preise morgen stabil bleiben oder stark schwanken. Verfügbar, sobald die morgigen Daten veröffentlicht sind (typischerweise 13:0014:00 MEZ). Niedrige Volatilität bedeutet recht konstante Preise Timing ist nicht kritisch. Hohe Volatilität bedeutet deutliche Preisunterschiede über den Tag gute Gelegenheit, energieintensive Aufgaben zu planen. `price_coefficient_variation_%` zeigt den Prozentwert, `price_spread` die absolute Preisspanne.",
"usage_tips": "Nutze dies für die Planung des morgigen Energieverbrauchs. Hohe Volatilität? Plane flexible Lasten in Best-Price-Perioden. Niedrige Volatilität? Lass Geräte laufen, wann es dir passt."
"description": "Preisvolatilitätsklassifizierung für morgen",
"long_description": "Zeigt, wie stark die Strompreise im Laufe des morgigen Tages variieren werden, basierend auf der Spannweite (Differenz zwischen höchstem und niedrigstem Preis). Wird nicht verfügbar, bis morgige Daten veröffentlicht sind (typischerweise 13:00-14:00 MEZ).",
"usage_tips": "Verwenden Sie dies zur Vorausplanung des morgigen Energieverbrauchs. Bei HOHER oder SEHR HOHER Volatilität morgen lohnt sich die Optimierung des Energieverbrauchs. Bei NIEDRIGER Volatilität können Sie Geräte jederzeit ohne wesentliche Kostenunterschiede betreiben."
},
"next_24h_volatility": {
"description": "Wie stark sich die Preise in den nächsten 24 Stunden verändern",
"long_description": "Zeigt die Preisvolatilität für ein rollierendes 24-Stunden-Fenster ab jetzt (aktualisiert alle 15 Minuten). Niedrige Volatilität bedeutet recht konstante Preise. Hohe Volatilität bedeutet spürbare Preisschwankungen und damit Chancen zur Optimierung. Im Unterschied zu Heute/Morgen-Sensoren überschreitet dieser Tagesgrenzen und liefert eine durchgängige Vorhersage. `price_coefficient_variation_%` zeigt den Prozentwert, `price_spread` die absolute Preisspanne.",
"usage_tips": "Am besten für Entscheidungen in Echtzeit. Nutze dies für Batterieladestrategien oder andere flexible Lasten, die über Mitternacht laufen könnten. Bietet eine konsistente 24h-Perspektive unabhängig vom Kalendertag."
"description": "Preisvolatilitätsklassifizierung für die rollierenden nächsten 24 Stunden",
"long_description": "Zeigt, wie stark die Strompreise in den nächsten 24 Stunden ab jetzt variieren (rollierendes Fenster). Dies überschreitet Tagesgrenzen und aktualisiert sich alle 15 Minuten, wodurch eine vorausschauende Volatilitätsbewertung unabhängig von Kalendertagen bereitgestellt wird.",
"usage_tips": "Bester Sensor für Echtzeitoptimierungsentscheidungen. Im Gegensatz zu Heute/Morgen-Sensoren, die um Mitternacht wechseln, bietet dies eine kontinuierliche 24h-Volatilitätsbewertung. Verwenden Sie dies für Batterielade-Strategien, die Tagesgrenzen überschreiten."
},
"today_tomorrow_volatility": {
"description": "Kombinierte Preisvolatilität für heute und morgen",
"long_description": "Zeigt die Gesamtvolatilität, wenn heute und morgen gemeinsam betrachtet werden (sobald die morgigen Daten verfügbar sind). Zeigt, ob über die Tagesgrenze hinweg deutliche Preisunterschiede bestehen. Fällt auf nur-heute zurück, wenn morgige Daten noch fehlen. Hilfreich für mehrtägige Optimierung. `price_coefficient_variation_%` zeigt den Prozentwert, `price_spread` die absolute Preisspanne.",
"usage_tips": "Nutze dies für Aufgaben, die sich über mehrere Tage erstrecken. Prüfe, ob die Preisunterschiede groß genug für eine Planung sind. Die einzelnen Tages-Sensoren zeigen die Beiträge pro Tag, falls du mehr Details brauchst."
"description": "Kombinierte Preisvolatilitätsklassifizierung für heute und morgen",
"long_description": "Zeigt die Volatilität über heute und morgen zusammen (wenn morgige Daten verfügbar sind). Bietet eine erweiterte Ansicht der Preisvariation über bis zu 48 Stunden. Fällt auf Nur-Heute zurück, wenn morgige Daten noch nicht verfügbar sind.",
"usage_tips": "Verwenden Sie dies für Mehrtagsplanung und um zu verstehen, ob Preismöglichkeiten über die Tagesgrenze hinweg bestehen. Die Attribute 'today_volatility' und 'tomorrow_volatility' zeigen individuelle Tagesbeiträge. Nützlich für die Planung von Ladesitzungen, die Mitternacht überschreiten könnten."
},
"data_lifecycle_status": {
"description": "Aktueller Status des Preisdaten-Lebenszyklus und der Zwischenspeicherung",
"long_description": "Zeigt an, ob die Integration zwischengespeicherte Daten oder frische Daten von der API verwendet. Zeigt aktuellen Lebenszyklus-Status: 'cached' (verwendet gespeicherte Daten), 'fresh' (gerade von API abgerufen), 'refreshing' (wird gerade abgerufen), 'searching_tomorrow' (sucht aktiv nach Morgendaten nach 13:00 Uhr), 'turnover_pending' (innerhalb 15 Minuten vor Mitternacht, 23:45-00:00) oder 'error' (Abruf fehlgeschlagen). Enthält umfassende Attribute wie Cache-Alter, nächste API-Abfragezeit, Datenvollständigkeit und API-Aufruf-Statistiken.",
"usage_tips": "Verwende diesen Diagnosesensor, um Datenaktualität und API-Aufrufmuster zu verstehen. Prüfe das 'cache_age'-Attribut, um zu sehen, wie alt die aktuellen Daten sind. Überwache 'next_api_poll', um zu wissen, wann das nächste Update geplant ist. Verwende 'data_completeness', um zu sehen, ob Daten für gestern/heute/morgen verfügbar sind. Der 'api_calls_today'-Zähler hilft, die API-Nutzung zu verfolgen. Perfekt zur Fehlersuche oder zum Verständnis des Integrationsverhaltens."
"price_forecast": {
"description": "Prognose kommender Strompreise",
"long_description": "Zeigt kommende Strompreise für zukünftige Intervalle in einem Format, das einfach in Dashboards verwendet werden kann",
"usage_tips": "Verwenden Sie die Attribute dieser Entität, um kommende Preise in Diagrammen oder benutzerdefinierten Karten anzuzeigen. Greifen Sie entweder auf 'intervals' für alle zukünftigen Intervalle oder auf 'hours' für stündliche Zusammenfassungen zu."
},
"best_price_end_time": {
"description": "Wann der aktuelle oder nächste günstige Zeitraum endet",
@ -322,14 +309,14 @@
"usage_tips": "Nutze dies, um einen Countdown wie 'Günstiger Zeitraum endet in 2 Stunden' (wenn aktiv) oder 'Nächster günstiger Zeitraum endet um 14:00' (wenn inaktiv) anzuzeigen. Home Assistant zeigt automatisch relative Zeit für Zeitstempel-Sensoren an."
},
"best_price_period_duration": {
"description": "Gesamtlänge des aktuellen oder nächsten günstigen Zeitraums",
"long_description": "Zeigt, wie lange der günstige Zeitraum insgesamt dauert. Der State wird in Stunden angezeigt (z. B. 1,5 h) für eine einfache Lesbarkeit in der UI, während das Attribut `period_duration_minutes` denselben Wert in Minuten bereitstellt (z. B. 90) für Automationen. Während eines aktiven Zeitraums zeigt dies die Dauer des aktuellen Zeitraums. Wenn kein Zeitraum aktiv ist, zeigt dies die Dauer des nächsten kommenden Zeitraums. Gibt nur 'Unbekannt' zurück, wenn keine Zeiträume ermittelt wurden.",
"usage_tips": "Für Anzeige: State-Wert (Stunden) in Dashboards nutzen. Für Automationen: Attribut `period_duration_minutes` verwenden, um zu prüfen, ob genug Zeit für langläufige Geräte ist (z. B. 'Wenn period_duration_minutes >= 90, starte Waschmaschine')."
"description": "Gesamtlänge des aktuellen oder nächsten günstigen Zeitraums in Minuten",
"long_description": "Zeigt, wie lange der günstige Zeitraum insgesamt dauert. Während eines aktiven Zeitraums zeigt dies die Dauer des aktuellen Zeitraums. Wenn kein Zeitraum aktiv ist, zeigt dies die Dauer des nächsten kommenden Zeitraums. Gibt nur 'Unbekannt' zurück, wenn keine Zeiträume ermittelt wurden.",
"usage_tips": "Nützlich für Planung: 'Der nächste günstige Zeitraum dauert 90 Minuten' oder 'Der aktuelle günstige Zeitraum ist 120 Minuten lang'. Kombiniere mit remaining_minutes, um zu berechnen, wann langlaufende Geräte gestartet werden sollten."
},
"best_price_remaining_minutes": {
"description": "Verbleibende Zeit im aktuellen günstigen Zeitraum",
"long_description": "Zeigt, wie viel Zeit im aktuellen günstigen Zeitraum noch verbleibt. Der State wird in Stunden angezeigt (z. B. 0,5 h) für eine einfache Lesbarkeit, während das Attribut `remaining_minutes` Minuten bereitstellt (z. B. 30) für Automationslogik. Gibt 0 zurück, wenn kein Zeitraum aktiv ist. Aktualisiert sich jede Minute. Prüfe binary_sensor.best_price_period, um zu sehen, ob ein Zeitraum aktuell aktiv ist.",
"usage_tips": "Für Automationen: Attribut `remaining_minutes` mit numerischen Vergleichen nutzen wie 'Wenn remaining_minutes > 0 UND remaining_minutes < 30, starte Waschmaschine jetzt'. Der Wert 0 macht es einfach zu prüfen, ob ein Zeitraum aktiv ist (Wert > 0) oder nicht (Wert = 0)."
"description": "Verbleibende Minuten im aktuellen günstigen Zeitraum (0 wenn inaktiv)",
"long_description": "Zeigt, wie viele Minuten im aktuellen günstigen Zeitraum noch verbleiben. Gibt 0 zurück, wenn kein Zeitraum aktiv ist. Aktualisiert sich jede Minute. Prüfe binary_sensor.best_price_period, um zu sehen, ob ein Zeitraum aktuell aktiv ist.",
"usage_tips": "Perfekt für Automatisierungen: 'Wenn remaining_minutes > 0 UND remaining_minutes < 30, starte Waschmaschine jetzt'. Der Wert 0 macht es einfach zu prüfen, ob ein Zeitraum aktiv ist (Wert > 0) oder nicht (Wert = 0)."
},
"best_price_progress": {
"description": "Fortschritt durch aktuellen günstigen Zeitraum (0% wenn inaktiv)",
@ -342,9 +329,9 @@
"usage_tips": "Immer nützlich für Vorausplanung: 'Nächster günstiger Zeitraum startet in 3 Stunden' (egal, ob du gerade in einem Zeitraum bist oder nicht). Kombiniere mit Automatisierungen: 'Wenn nächste Startzeit in 10 Minuten ist, sende Benachrichtigung zur Vorbereitung der Waschmaschine'."
},
"best_price_next_in_minutes": {
"description": "Zeit bis zum nächsten günstigen Zeitraum",
"long_description": "Zeigt, wie lange es bis zum nächsten günstigen Zeitraum dauert. Der State wird in Stunden angezeigt (z. B. 2,25 h) für Dashboards, während das Attribut `next_in_minutes` Minuten bereitstellt (z. B. 135) für Automationsbedingungen. Während eines aktiven Zeitraums zeigt dies die Zeit bis zum Zeitraum nach dem aktuellen. Gibt 0 während kurzer Übergangsphasen zurück. Aktualisiert sich jede Minute.",
"usage_tips": "Für Automationen: Attribut `next_in_minutes` nutzen wie 'Wenn next_in_minutes > 0 UND next_in_minutes < 15, warte, bevor du die Geschirrspülmaschine startest'. Wert > 0 zeigt immer an, dass ein zukünftiger Zeitraum geplant ist."
"description": "Minuten bis nächster günstiger Zeitraum startet (0 beim Übergang)",
"long_description": "Zeigt Minuten bis der nächste günstige Zeitraum startet. Während eines aktiven Zeitraums zeigt dies die Zeit bis zum Zeitraum nach dem aktuellen. Gibt 0 während kurzer Übergangsphasen zurück. Aktualisiert sich jede Minute.",
"usage_tips": "Perfekt für 'warte bis günstiger Zeitraum' Automatisierungen: 'Wenn next_in_minutes > 0 UND next_in_minutes < 15, warte, bevor du die Geschirrspülmaschine startest'. Wert > 0 zeigt immer an, dass ein zukünftiger Zeitraum geplant ist."
},
"peak_price_end_time": {
"description": "Wann der aktuelle oder nächste teure Zeitraum endet",
@ -352,14 +339,14 @@
"usage_tips": "Nutze dies, um 'Teurer Zeitraum endet in 1 Stunde' (wenn aktiv) oder 'Nächster teurer Zeitraum endet um 18:00' (wenn inaktiv) anzuzeigen. Kombiniere mit Automatisierungen, um den Betrieb nach der Spitzenzeit fortzusetzen."
},
"peak_price_period_duration": {
"description": "Länge des aktuellen/nächsten teuren Zeitraums",
"long_description": "Gesamtdauer des aktuellen oder nächsten teuren Zeitraums. Der State wird in Stunden angezeigt (z. B. 1,5 h) für leichtes Ablesen in der UI, während das Attribut `period_duration_minutes` denselben Wert in Minuten bereitstellt (z. B. 90) für Automationen. Dieser Wert repräsentiert die **volle geplante Dauer** des Zeitraums und ist konstant während des gesamten Zeitraums, auch wenn die verbleibende Zeit (remaining_minutes) abnimmt.",
"usage_tips": "Kombiniere mit remaining_minutes, um zu berechnen, wann langlaufende Geräte gestoppt werden sollen: Zeitraum begann vor `period_duration_minutes - remaining_minutes` Minuten. Dieses Attribut unterstützt Energiespar-Strategien, indem es hilft, Hochverbrauchsaktivitäten außerhalb teurer Perioden zu planen."
"description": "Gesamtlänge des aktuellen oder nächsten teuren Zeitraums in Minuten",
"long_description": "Zeigt, wie lange der teure Zeitraum insgesamt dauert. Während eines aktiven Zeitraums zeigt dies die Dauer des aktuellen Zeitraums. Wenn kein Zeitraum aktiv ist, zeigt dies die Dauer des nächsten kommenden Zeitraums. Gibt nur 'Unbekannt' zurück, wenn keine Zeiträume ermittelt wurden.",
"usage_tips": "Nützlich für Planung: 'Der nächste teure Zeitraum dauert 60 Minuten' oder 'Der aktuelle Spitzenzeitraum ist 90 Minuten lang'. Kombiniere mit remaining_minutes, um zu entscheiden, ob die Spitze abgewartet oder der Betrieb fortgesetzt werden soll."
},
"peak_price_remaining_minutes": {
"description": "Verbleibende Zeit im aktuellen teuren Zeitraum",
"long_description": "Zeigt, wie viel Zeit im aktuellen teuren Zeitraum noch verbleibt. Der State wird in Stunden angezeigt (z. B. 0,75 h) für einfaches Ablesen in Dashboards, während das Attribut `remaining_minutes` dieselbe Zeit in Minuten liefert (z. B. 45) für Automationsbedingungen. **Countdown-Timer**: Dieser Wert dekrementiert jede Minute während eines aktiven Zeitraums. Gibt 0 zurück, wenn kein teurer Zeitraum aktiv ist. Aktualisiert sich minütlich.",
"usage_tips": "Für Automationen: Nutze Attribut `remaining_minutes` wie 'Wenn remaining_minutes > 60, setze Heizung auf Energiesparmodus' oder 'Wenn remaining_minutes < 15, erhöhe Temperatur wieder'. UI zeigt benutzerfreundliche Stunden (z. B. 1,25 h). Wert 0 zeigt an, dass kein teurer Zeitraum aktiv ist."
"description": "Verbleibende Minuten im aktuellen teuren Zeitraum (0 wenn inaktiv)",
"long_description": "Zeigt, wie viele Minuten im aktuellen teuren Zeitraum noch verbleiben. Gibt 0 zurück, wenn kein Zeitraum aktiv ist. Aktualisiert sich jede Minute. Prüfe binary_sensor.peak_price_period, um zu sehen, ob ein Zeitraum aktuell aktiv ist.",
"usage_tips": "Nutze in Automatisierungen: 'Wenn remaining_minutes > 60, breche aufgeschobene Ladesitzung ab'. Wert 0 macht es einfach zu unterscheiden zwischen aktivem (Wert > 0) und inaktivem (Wert = 0) Zeitraum."
},
"peak_price_progress": {
"description": "Fortschritt durch aktuellen teuren Zeitraum (0% wenn inaktiv)",
@ -372,9 +359,9 @@
"usage_tips": "Immer nützlich für Planung: 'Nächster teurer Zeitraum startet in 2 Stunden'. Automatisierung: 'Wenn nächste Startzeit in 30 Minuten ist, reduziere Heiztemperatur vorsorglich'."
},
"peak_price_next_in_minutes": {
"description": "Zeit bis zum nächsten teuren Zeitraum",
"long_description": "Zeigt, wie lange es bis zum nächsten teuren Zeitraum dauert. Der State wird in Stunden angezeigt (z. B. 2,25 h) für Dashboards, während das Attribut `next_in_minutes` Minuten bereitstellt (z. B. 135) für Automationsbedingungen. Während eines aktiven Zeitraums zeigt dies die Zeit bis zum Zeitraum nach dem aktuellen. Gibt 0 während kurzer Übergangsphasen zurück. Aktualisiert sich jede Minute.",
"usage_tips": "Für Automationen: Attribut `next_in_minutes` nutzen wie 'Wenn next_in_minutes > 0 UND next_in_minutes < 10, reduziere Heizung vorsorglich bevor der teure Zeitraum beginnt'. Wert > 0 zeigt immer an, dass ein zukünftiger teurer Zeitraum geplant ist."
"description": "Minuten bis nächster teurer Zeitraum startet (0 beim Übergang)",
"long_description": "Zeigt Minuten bis der nächste teure Zeitraum startet. Während eines aktiven Zeitraums zeigt dies die Zeit bis zum Zeitraum nach dem aktuellen. Gibt 0 während kurzer Übergangsphasen zurück. Aktualisiert sich jede Minute.",
"usage_tips": "Präventive Automatisierung: 'Wenn next_in_minutes > 0 UND next_in_minutes < 10, beende aktuellen Ladezyklus jetzt, bevor die Preise steigen'."
},
"home_type": {
"description": "Art der Wohnung (Wohnung, Haus usw.)",
@ -450,11 +437,6 @@
"description": "Datenexport für Dashboard-Integrationen",
"long_description": "Dieser Sensor ruft den get_chartdata-Service mit deiner konfigurierten YAML-Konfiguration auf und stellt das Ergebnis als Entity-Attribute bereit. Der Status zeigt 'ready' wenn Daten verfügbar sind, 'error' bei Fehlern, oder 'pending' vor dem ersten Aufruf. Perfekt für Dashboard-Integrationen wie ApexCharts, die Preisdaten aus Entity-Attributen lesen.",
"usage_tips": "Konfiguriere die YAML-Parameter in den Integrationsoptionen entsprechend deinem get_chartdata-Service-Aufruf. Der Sensor aktualisiert automatisch bei Preisdaten-Updates (typischerweise nach Mitternacht und wenn morgige Daten eintreffen). Greife auf die Service-Response-Daten direkt über die Entity-Attribute zu - die Struktur entspricht exakt dem, was get_chartdata zurückgibt."
},
"chart_metadata": {
"description": "Leichtgewichtige Metadaten für Diagrammkonfiguration",
"long_description": "Liefert wesentliche Diagrammkonfigurationswerte als Sensor-Attribute. Nützlich für jede Diagrammkarte, die Y-Achsen-Grenzen benötigt. Der Sensor ruft get_chartdata im Nur-Metadaten-Modus auf (keine Datenverarbeitung) und extrahiert: yaxis_min, yaxis_max (vorgeschlagener Y-Achsenbereich für optimale Skalierung). Der Status spiegelt das Service-Call-Ergebnis wider: 'ready' bei Erfolg, 'error' bei Fehler, 'pending' während der Initialisierung.",
"usage_tips": "Konfiguriere über configuration.yaml unter tibber_prices.chart_metadata_config (optional: day, subunit_currency, resolution). Der Sensor aktualisiert sich automatisch bei Preisdatenänderungen. Greife auf Metadaten aus Attributen zu: yaxis_min, yaxis_max. Verwende mit config-template-card oder jedem Tool, das Entity-Attribute liest - perfekt für dynamische Diagrammkonfiguration ohne manuelle Berechnungen."
}
},
"binary_sensor": {
@ -489,95 +471,11 @@
"usage_tips": "Verwende dies, um zu überprüfen, ob Echtzeit-Verbrauchsdaten verfügbar sind. Aktiviere Benachrichtigungen, falls dies unerwartet auf 'Aus' wechselt, was auf potenzielle Hardware- oder Verbindungsprobleme hinweist."
}
},
"number": {
"best_price_flex_override": {
"description": "Maximaler Prozentsatz über dem Tagesminimumpreis, den Intervalle haben können und trotzdem als 'Bestpreis' gelten. Empfohlen: 15-20 mit Lockerung aktiviert (Standard), oder 25-35 ohne Lockerung. Maximum: 50 (Obergrenze für zuverlässige Periodenerkennung).",
"long_description": "Wenn diese Entität aktiviert ist, überschreibt ihr Wert die Einstellung 'Flexibilität' aus dem Optionen-Dialog für die Bestpreis-Periodenberechnung.",
"usage_tips": "Aktiviere diese Entität, um die Bestpreiserkennung dynamisch über Automatisierungen anzupassen, z.B. höhere Flexibilität bei kritischen Lasten oder engere Anforderungen für flexible Geräte."
},
"best_price_min_distance_override": {
"description": "Minimaler prozentualer Abstand unter dem Tagesdurchschnitt. Intervalle müssen so weit unter dem Durchschnitt liegen, um als 'Bestpreis' zu gelten. Hilft, echte Niedrigpreis-Perioden von durchschnittlichen Preisen zu unterscheiden.",
"long_description": "Wenn diese Entität aktiviert ist, überschreibt ihr Wert die Einstellung 'Mindestabstand' aus dem Optionen-Dialog für die Bestpreis-Periodenberechnung.",
"usage_tips": "Erhöhe den Wert, wenn du strengere Bestpreis-Kriterien möchtest. Verringere ihn, wenn zu wenige Perioden erkannt werden."
},
"best_price_min_period_length_override": {
"description": "Minimale Periodenl\u00e4nge in 15-Minuten-Intervallen. Perioden kürzer als diese werden nicht gemeldet. Beispiel: 2 = mindestens 30 Minuten.",
"long_description": "Wenn diese Entität aktiviert ist, überschreibt ihr Wert die Einstellung 'Mindestperiodenlänge' aus dem Optionen-Dialog für die Bestpreis-Periodenberechnung.",
"usage_tips": "Passe an die typische Laufzeit deiner Geräte an: 2 (30 Min) für Schnellprogramme, 4-8 (1-2 Std) für normale Zyklen, 8+ für lange ECO-Programme."
},
"best_price_min_periods_override": {
"description": "Minimale Anzahl an Bestpreis-Perioden, die täglich gefunden werden sollen. Wenn Lockerung aktiviert ist, wird das System die Kriterien automatisch anpassen, um diese Zahl zu erreichen.",
"long_description": "Wenn diese Entität aktiviert ist, überschreibt ihr Wert die Einstellung 'Mindestperioden' aus dem Optionen-Dialog für die Bestpreis-Periodenberechnung.",
"usage_tips": "Setze dies auf die Anzahl zeitkritischer Aufgaben, die du täglich hast. Beispiel: 2 für zwei Waschmaschinenladungen."
},
"best_price_relaxation_attempts_override": {
"description": "Anzahl der Versuche, die Kriterien schrittweise zu lockern, um die Mindestperiodenanzahl zu erreichen. Jeder Versuch erhöht die Flexibilität um 3 Prozent. Bei 0 werden nur Basis-Kriterien verwendet.",
"long_description": "Wenn diese Entität aktiviert ist, überschreibt ihr Wert die Einstellung 'Lockerungsversuche' aus dem Optionen-Dialog für die Bestpreis-Periodenberechnung.",
"usage_tips": "Höhere Werte machen die Periodenerkennung anpassungsfähiger an Tage mit stabilen Preisen. Setze auf 0, um strenge Kriterien ohne Lockerung zu erzwingen."
},
"best_price_gap_count_override": {
"description": "Maximale Anzahl teurerer Intervalle, die zwischen günstigen Intervallen erlaubt sind und trotzdem als eine zusammenhängende Periode gelten. Bei 0 müssen günstige Intervalle aufeinander folgen.",
"long_description": "Wenn diese Entität aktiviert ist, überschreibt ihr Wert die Einstellung 'Lückentoleranz' aus dem Optionen-Dialog für die Bestpreis-Periodenberechnung.",
"usage_tips": "Erhöhe dies für Geräte mit variabler Last (z.B. Wärmepumpen), die kurze teurere Intervalle tolerieren können. Setze auf 0 für kontinuierliche günstige Perioden."
},
"peak_price_flex_override": {
"description": "Maximaler Prozentsatz unter dem Tagesmaximumpreis, den Intervalle haben können und trotzdem als 'Spitzenpreis' gelten. Gleiche Empfehlungen wie für Bestpreis-Flexibilität.",
"long_description": "Wenn diese Entität aktiviert ist, überschreibt ihr Wert die Einstellung 'Flexibilität' aus dem Optionen-Dialog für die Spitzenpreis-Periodenberechnung.",
"usage_tips": "Nutze dies, um den Spitzenpreis-Schwellenwert zur Laufzeit für Automatisierungen anzupassen, die den Verbrauch während teurer Stunden vermeiden."
},
"peak_price_min_distance_override": {
"description": "Minimaler prozentualer Abstand über dem Tagesdurchschnitt. Intervalle müssen so weit über dem Durchschnitt liegen, um als 'Spitzenpreis' zu gelten.",
"long_description": "Wenn diese Entität aktiviert ist, überschreibt ihr Wert die Einstellung 'Mindestabstand' aus dem Optionen-Dialog für die Spitzenpreis-Periodenberechnung.",
"usage_tips": "Erhöhe den Wert, um nur extreme Preisspitzen zu erfassen. Verringere ihn, um mehr Hochpreiszeiten einzubeziehen."
},
"peak_price_min_period_length_override": {
"description": "Minimale Periodenl\u00e4nge in 15-Minuten-Intervallen für Spitzenpreise. Kürzere Preisspitzen werden nicht als Perioden gemeldet.",
"long_description": "Wenn diese Entität aktiviert ist, überschreibt ihr Wert die Einstellung 'Mindestperiodenlänge' aus dem Optionen-Dialog für die Spitzenpreis-Periodenberechnung.",
"usage_tips": "Kürzere Werte erfassen kurze Preisspitzen. Längere Werte fokussieren auf anhaltende Hochpreisphasen."
},
"peak_price_min_periods_override": {
"description": "Minimale Anzahl an Spitzenpreis-Perioden, die täglich gefunden werden sollen.",
"long_description": "Wenn diese Entität aktiviert ist, überschreibt ihr Wert die Einstellung 'Mindestperioden' aus dem Optionen-Dialog für die Spitzenpreis-Periodenberechnung.",
"usage_tips": "Setze dies basierend darauf, wie viele Hochpreisphasen du pro Tag für Automatisierungen erfassen möchtest."
},
"peak_price_relaxation_attempts_override": {
"description": "Anzahl der Versuche, die Kriterien zu lockern, um die Mindestanzahl an Spitzenpreis-Perioden zu erreichen.",
"long_description": "Wenn diese Entität aktiviert ist, überschreibt ihr Wert die Einstellung 'Lockerungsversuche' aus dem Optionen-Dialog für die Spitzenpreis-Periodenberechnung.",
"usage_tips": "Erhöhe dies, wenn an Tagen mit stabilen Preisen keine Perioden gefunden werden. Setze auf 0, um strenge Kriterien zu erzwingen."
},
"peak_price_gap_count_override": {
"description": "Maximale Anzahl günstigerer Intervalle, die zwischen teuren Intervallen erlaubt sind und trotzdem als eine Spitzenpreis-Periode gelten.",
"long_description": "Wenn diese Entität aktiviert ist, überschreibt ihr Wert die Einstellung 'Lückentoleranz' aus dem Optionen-Dialog für die Spitzenpreis-Periodenberechnung.",
"usage_tips": "Höhere Werte erfassen längere Hochpreisphasen auch mit kurzen Preiseinbrüchen. Setze auf 0, um strikt zusammenhängende Spitzenpreise zu erfassen."
}
},
"switch": {
"best_price_enable_relaxation_override": {
"description": "Wenn aktiviert, werden die Kriterien automatisch gelockert, um die Mindestperiodenanzahl zu erreichen. Wenn deaktiviert, werden nur Perioden gemeldet, die die strengen Kriterien erfüllen (möglicherweise null Perioden bei stabilen Preisen).",
"long_description": "Wenn diese Entität aktiviert ist, überschreibt ihr Wert die Einstellung 'Mindestanzahl erreichen' aus dem Optionen-Dialog für die Bestpreis-Periodenberechnung.",
"usage_tips": "Aktiviere dies für garantierte tägliche Automatisierungsmöglichkeiten. Deaktiviere es, wenn du nur wirklich günstige Zeiträume willst, auch wenn das bedeutet, dass an manchen Tagen keine Perioden gefunden werden."
},
"peak_price_enable_relaxation_override": {
"description": "Wenn aktiviert, werden die Kriterien automatisch gelockert, um die Mindestperiodenanzahl zu erreichen. Wenn deaktiviert, werden nur echte Preisspitzen gemeldet.",
"long_description": "Wenn diese Entität aktiviert ist, überschreibt ihr Wert die Einstellung 'Mindestanzahl erreichen' aus dem Optionen-Dialog für die Spitzenpreis-Periodenberechnung.",
"usage_tips": "Aktiviere dies für konsistente Spitzenpreis-Warnungen. Deaktiviere es, um nur extreme Preisspitzen zu erfassen."
}
},
"home_types": {
"APARTMENT": "Wohnung",
"ROWHOUSE": "Reihenhaus",
"HOUSE": "Haus",
"COTTAGE": "Ferienhaus"
},
"time_units": {
"day": "{count} Tag",
"days": "{count} Tagen",
"hour": "{count} Stunde",
"hours": "{count} Stunden",
"minute": "{count} Minute",
"minutes": "{count} Minuten",
"ago": "vor {parts}",
"now": "jetzt"
},
"attribution": "Daten bereitgestellt von Tibber"
}

View file

@ -1,20 +1,7 @@
{
"apexcharts": {
"title_rating_level": "Price Phases Daily Progress",
"title_level": "Price Level",
"hourly_suffix": "(Ø hourly)",
"best_price_period_name": "Best Price Period",
"peak_price_period_name": "Peak Price Period",
"notification": {
"metadata_sensor_unavailable": {
"title": "Tibber Prices: ApexCharts YAML Generated with Limited Functionality",
"message": "You just generated an ApexCharts card configuration via Developer Tools. The Chart Metadata sensor is currently disabled, so the generated YAML will only show **basic functionality** (auto-scale axis, fixed gradient at 50%).\n\n**To enable full functionality** (optimized scaling, dynamic gradient colors):\n1. [Open Tibber Prices Integration](https://my.home-assistant.io/redirect/integration/?domain=tibber_prices)\n2. Enable the 'Chart Metadata' sensor\n3. **Generate the YAML again** via Developer Tools\n4. **Replace the old YAML** in your dashboard with the new version\n\n⚠ Simply enabling the sensor is not enough - you must regenerate and replace the YAML code!"
},
"missing_cards": {
"title": "Tibber Prices: ApexCharts YAML Cannot Be Used",
"message": "You just generated an ApexCharts card configuration via Developer Tools, but the generated YAML **will not work** because required custom cards are missing.\n\n**Missing cards:**\n{cards}\n\n**To use the generated YAML:**\n1. Click the links above to install the missing cards from HACS\n2. Restart Home Assistant (sometimes needed)\n3. **Generate the YAML again** via Developer Tools\n4. Add the YAML to your dashboard\n\n⚠ The current YAML code will not work until all cards are installed!"
}
}
"title_level": "Price Level"
},
"sensor": {
"current_interval_price": {
@ -22,9 +9,9 @@
"long_description": "Shows the current price per kWh from your Tibber subscription",
"usage_tips": "Use this to track prices or to create automations that run when electricity is cheap"
},
"current_interval_price_base": {
"description": "Current electricity price in base currency (EUR/kWh, NOK/kWh, etc.) for Energy Dashboard",
"long_description": "Shows the current price per kWh in base currency units (e.g., EUR/kWh instead of ct/kWh, NOK/kWh instead of øre/kWh). This sensor is specifically designed for use with Home Assistant's Energy Dashboard, which requires prices in standard currency units.",
"current_interval_price_major": {
"description": "Current electricity price in major currency (EUR/kWh, NOK/kWh, etc.) for Energy Dashboard",
"long_description": "Shows the current price per kWh in major currency units (e.g., EUR/kWh instead of ct/kWh, NOK/kWh instead of øre/kWh). This sensor is specifically designed for use with Home Assistant's Energy Dashboard, which requires prices in standard currency units.",
"usage_tips": "Use this sensor when configuring the Energy Dashboard under Settings → Dashboards → Energy. Select this sensor as the 'Entity with current price' to automatically calculate your energy costs. The Energy Dashboard multiplies your energy consumption (kWh) by this price to show total costs."
},
"next_interval_price": {
@ -58,9 +45,9 @@
"usage_tips": "Use this to avoid running appliances during peak price times"
},
"average_price_today": {
"description": "The typical electricity price for today per kWh (configurable display format)",
"long_description": "Shows the typical price per kWh for today. **By default, the state displays the median** (resistant to extreme spikes, showing what you can generally expect). You can change this in the integration options to show the arithmetic mean instead. The alternate value is always available as attribute `price_mean` or `price_median` for automations.",
"usage_tips": "Use the state value for display. For exact cost calculations in automations, use: {{ state_attr('sensor.average_price_today', 'price_mean') }}"
"description": "The average electricity price for today per kWh",
"long_description": "Shows the average price per kWh for the current day from your Tibber subscription",
"usage_tips": "Use this as a baseline for comparing current prices"
},
"lowest_price_tomorrow": {
"description": "The lowest electricity price for tomorrow per kWh",
@ -73,9 +60,9 @@
"usage_tips": "Use this to avoid running appliances during tomorrow's peak price times. Helpful for planning around expensive periods."
},
"average_price_tomorrow": {
"description": "The typical electricity price for tomorrow per kWh (configurable display format)",
"long_description": "Shows the typical price per kWh for tomorrow. **By default, the state displays the median** (resistant to extreme spikes). You can change this in the integration options to show the arithmetic mean instead. The alternate value is available as attribute. This sensor becomes unavailable until tomorrow's data is published by Tibber (typically around 13:00-14:00 CET).",
"usage_tips": "Use this to plan tomorrow's energy consumption. For cost calculations, use: {{ state_attr('sensor.average_price_tomorrow', 'price_mean') }}"
"description": "The average electricity price for tomorrow per kWh",
"long_description": "Shows the average price per kWh for tomorrow from your Tibber subscription. This sensor becomes unavailable until tomorrow's data is published by Tibber (typically around 13:00-14:00 CET).",
"usage_tips": "Use this as a baseline for comparing tomorrow's prices and planning consumption. Compare with today's average to see if tomorrow will be more or less expensive overall."
},
"yesterday_price_level": {
"description": "Aggregated price level for yesterday",
@ -108,14 +95,14 @@
"usage_tips": "Use this to plan tomorrow's energy consumption based on your personalized price thresholds. Compare with today to decide if you should shift consumption to tomorrow or use energy today."
},
"trailing_price_average": {
"description": "The typical electricity price for the past 24 hours per kWh (configurable display format)",
"long_description": "Shows the typical price per kWh for the past 24 hours. **By default, the state displays the median** (resistant to extreme spikes, showing what price level was typical). You can change this in the integration options to show the arithmetic mean instead. The alternate value is available as attribute. Updates every 15 minutes.",
"usage_tips": "Use the state value to see the typical recent price level. For cost calculations, use: {{ state_attr('sensor.trailing_price_average', 'price_mean') }}"
"description": "The average electricity price for the past 24 hours per kWh",
"long_description": "Shows the average price per kWh calculated from the past 24 hours (trailing average) from your Tibber subscription. This provides a rolling average that updates every 15 minutes based on historical data.",
"usage_tips": "Use this to compare current prices against recent trends. A current price significantly above this average may indicate a good time to reduce consumption."
},
"leading_price_average": {
"description": "The typical electricity price for the next 24 hours per kWh (configurable display format)",
"long_description": "Shows the typical price per kWh for the next 24 hours. **By default, the state displays the median** (resistant to extreme spikes, showing what price level to expect). You can change this in the integration options to show the arithmetic mean instead. The alternate value is available as attribute.",
"usage_tips": "Use the state value to see the typical upcoming price level. For cost calculations, use: {{ state_attr('sensor.leading_price_average', 'price_mean') }}"
"description": "The average electricity price for the next 24 hours per kWh",
"long_description": "Shows the average price per kWh calculated from the next 24 hours (leading average) from your Tibber subscription. This provides a forward-looking average based on available forecast data.",
"usage_tips": "Use this to plan energy usage. If the current price is below the leading average, it may be a good time to run energy-intensive appliances."
},
"trailing_price_min": {
"description": "The minimum electricity price for the past 24 hours per kWh",
@ -292,29 +279,29 @@
"long_description": "Shows the timestamp of the latest available price data interval from your Tibber subscription"
},
"today_volatility": {
"description": "How much electricity prices change throughout today",
"long_description": "Indicates whether today's prices are stable or have big swings. Low volatility means prices stay fairly consistent—timing doesn't matter much. High volatility means significant price differences throughout the day—great opportunity to shift consumption to cheaper periods. Check `price_coefficient_variation_%` for the variance percentage and `price_spread` for the absolute price span.",
"usage_tips": "Use this to decide if optimization is worth your effort. On low-volatility days, you can run devices anytime. On high-volatility days, following Best Price periods saves meaningful money."
"description": "Price volatility classification for today",
"long_description": "Shows how much electricity prices vary throughout today based on the spread (difference between highest and lowest price). Classification: LOW = spread < 5ct, MODERATE = 5-15ct, HIGH = 15-30ct, VERY HIGH = >30ct.",
"usage_tips": "Use this to decide if price-based optimization is worthwhile. For example, with a balcony battery that has 15% efficiency losses, optimization only makes sense when volatility is at least MODERATE. Create automations that check volatility before scheduling charging/discharging cycles."
},
"tomorrow_volatility": {
"description": "How much electricity prices will change tomorrow",
"long_description": "Indicates whether tomorrow's prices will be stable or have big swings. Available once tomorrow's data is published (typically 13:00-14:00 CET). Low volatility means prices stay fairly consistent—timing isn't critical. High volatility means significant price differences throughout the day—good opportunity for scheduling energy-intensive activities. Check `price_coefficient_variation_%` for the variance percentage and `price_spread` for the absolute price span.",
"usage_tips": "Use for planning tomorrow's energy consumption. High volatility? Schedule flexible loads during Best Price periods. Low volatility? Run devices whenever is convenient."
"description": "Price volatility classification for tomorrow",
"long_description": "Shows how much electricity prices will vary throughout tomorrow based on the spread (difference between highest and lowest price). Becomes unavailable until tomorrow's data is published (typically 13:00-14:00 CET).",
"usage_tips": "Use this for advance planning of tomorrow's energy usage. If tomorrow has HIGH or VERY HIGH volatility, it's worth optimizing energy consumption timing. If LOW, you can run devices anytime without significant cost differences."
},
"next_24h_volatility": {
"description": "How much prices will change over the next 24 hours",
"long_description": "Indicates price volatility for a rolling 24-hour window from now (updates every 15 minutes). Low volatility means prices stay fairly consistent. High volatility means significant price swings offer optimization opportunities. Unlike today/tomorrow sensors, this crosses day boundaries and provides a continuous forward-looking assessment. Check `price_coefficient_variation_%` for the variance percentage and `price_spread` for the absolute price span.",
"usage_tips": "Best for real-time decisions. Use when planning battery charging strategies or other flexible loads that might span across midnight. Provides consistent 24h perspective regardless of calendar day."
"description": "Price volatility classification for the rolling next 24 hours",
"long_description": "Shows how much electricity prices vary in the next 24 hours from now (rolling window). This crosses day boundaries and updates every 15 minutes, providing a forward-looking volatility assessment independent of calendar days.",
"usage_tips": "Best sensor for real-time optimization decisions. Unlike today/tomorrow sensors that switch at midnight, this provides continuous 24h volatility assessment. Use for battery charging strategies that span across day boundaries."
},
"today_tomorrow_volatility": {
"description": "Combined price volatility across today and tomorrow",
"long_description": "Shows overall price volatility when considering both today and tomorrow together (when available). Indicates whether there are significant price differences across the day boundary. Falls back to today-only when tomorrow's data isn't available yet. Useful for understanding multi-day optimization opportunities. Check `price_coefficient_variation_%` for the variance percentage and `price_spread` for the absolute price span.",
"usage_tips": "Use for planning tasks that span multiple days. Check if prices vary enough to make scheduling worthwhile. The individual day volatility sensors show breakdown per day if you need more detail."
"description": "Combined price volatility classification for today and tomorrow",
"long_description": "Shows volatility across both today and tomorrow combined (when tomorrow's data is available). Provides an extended view of price variation spanning up to 48 hours. Falls back to today-only when tomorrow's data isn't available yet.",
"usage_tips": "Use this for multi-day planning and to understand if price opportunities exist across the day boundary. The 'today_volatility' and 'tomorrow_volatility' breakdown attributes show individual day contributions. Useful for scheduling charging sessions that might span midnight."
},
"data_lifecycle_status": {
"description": "Current state of price data lifecycle and caching",
"long_description": "Shows whether the integration is using cached data or fresh data from the API. Displays current lifecycle state: 'cached' (using stored data), 'fresh' (just fetched from API), 'refreshing' (currently fetching), 'searching_tomorrow' (actively polling for tomorrow's data after 13:00), 'turnover_pending' (within 15 minutes of midnight, 23:45-00:00), or 'error' (fetch failed). Includes comprehensive attributes like cache age, next API poll time, data completeness, and API call statistics.",
"usage_tips": "Use this diagnostic sensor to understand data freshness and API call patterns. Check 'cache_age' attribute to see how old the current data is. Monitor 'next_api_poll' to know when the next update is scheduled. Use 'data_completeness' to see if yesterday/today/tomorrow data is available. The 'api_calls_today' counter helps track API usage. Perfect for troubleshooting or understanding the integration's behavior."
"price_forecast": {
"description": "Forecast of upcoming electricity prices",
"long_description": "Shows upcoming electricity prices for future intervals in a format that's easy to use in dashboards",
"usage_tips": "Use this entity's attributes to display upcoming prices in charts or custom cards. Access either 'intervals' for all future intervals or 'hours' for hourly summaries."
},
"best_price_end_time": {
"description": "When the current or next best price period ends",
@ -322,14 +309,14 @@
"usage_tips": "Use this to display a countdown like 'Cheap period ends in 2 hours' (when active) or 'Next cheap period ends at 14:00' (when inactive). Home Assistant automatically shows relative time for timestamp sensors."
},
"best_price_period_duration": {
"description": "Total length of current or next best price period",
"long_description": "Shows how long the best price period lasts in total. The state is displayed in hours (e.g., 1.5 h) for easy reading in the UI, while the `period_duration_minutes` attribute provides the same value in minutes (e.g., 90) for use in automations. During an active period, shows the duration of the current period. When no period is active, shows the duration of the next upcoming period. Returns 'Unknown' only when no periods are configured.",
"usage_tips": "For display: Use the state value (hours) in dashboards. For automations: Use `period_duration_minutes` attribute to check if there's enough time for long-running tasks (e.g., 'If period_duration_minutes >= 90, start washing machine')."
"description": "Total length of current or next best price period in minutes",
"long_description": "Shows how long the best price period lasts in total. During an active period, shows the duration of the current period. When no period is active, shows the duration of the next upcoming period. Returns 'Unknown' only when no periods are configured.",
"usage_tips": "Useful for planning: 'The next cheap period lasts 90 minutes' or 'Current cheap period is 120 minutes long'. Combine with remaining_minutes to calculate when to start long-running appliances."
},
"best_price_remaining_minutes": {
"description": "Time remaining in current best price period",
"long_description": "Shows how much time is left in the current best price period. The state displays in hours (e.g., 0.5 h) for easy reading, while the `remaining_minutes` attribute provides minutes (e.g., 30) for automation logic. Returns 0 when no period is active. Updates every minute. Check binary_sensor.best_price_period to see if a period is currently active.",
"usage_tips": "For automations: Use `remaining_minutes` attribute with numeric comparisons like 'If remaining_minutes > 0 AND remaining_minutes < 30, start washing machine now'. The value 0 makes it easy to check if a period is active (value > 0) or not (value = 0)."
"description": "Minutes remaining in current best price period (0 when inactive)",
"long_description": "Shows how many minutes are left in the current best price period. Returns 0 when no period is active. Updates every minute. Check binary_sensor.best_price_period to see if a period is currently active.",
"usage_tips": "Perfect for automations: 'If remaining_minutes > 0 AND remaining_minutes < 30, start washing machine now'. The value 0 makes it easy to check if a period is active (value > 0) or not (value = 0)."
},
"best_price_progress": {
"description": "Progress through current best price period (0% when inactive)",
@ -342,9 +329,9 @@
"usage_tips": "Always useful for planning ahead: 'Next cheap period starts in 3 hours' (whether you're in a period now or not). Combine with automations: 'When next start time is in 10 minutes, send notification to prepare washing machine'."
},
"best_price_next_in_minutes": {
"description": "Time until next best price period starts",
"long_description": "Shows how long until the next best price period starts. The state displays in hours (e.g., 2.25 h) for dashboards, while the `next_in_minutes` attribute provides minutes (e.g., 135) for automation conditions. During an active period, shows time until the period AFTER the current one. Returns 0 during brief transition moments. Updates every minute.",
"usage_tips": "For automations: Use `next_in_minutes` attribute like 'If next_in_minutes > 0 AND next_in_minutes < 15, wait before starting dishwasher'. Value > 0 always indicates a future period is scheduled."
"description": "Minutes until next best price period starts (0 when in transition)",
"long_description": "Shows minutes until the next best price period starts. During an active period, shows time until the period AFTER the current one. Returns 0 during brief transition moments. Updates every minute.",
"usage_tips": "Perfect for 'wait until cheap period' automations: 'If next_in_minutes > 0 AND next_in_minutes < 15, wait before starting dishwasher'. Value > 0 always indicates a future period is scheduled."
},
"peak_price_end_time": {
"description": "When the current or next peak price period ends",
@ -352,14 +339,14 @@
"usage_tips": "Use this to display 'Expensive period ends in 1 hour' (when active) or 'Next expensive period ends at 18:00' (when inactive). Combine with automations to resume operations after peak."
},
"peak_price_period_duration": {
"description": "Total length of current or next peak price period",
"long_description": "Shows how long the peak price period lasts in total. The state is displayed in hours (e.g., 0.75 h) for easy reading in the UI, while the `period_duration_minutes` attribute provides the same value in minutes (e.g., 45) for use in automations. During an active period, shows the duration of the current period. When no period is active, shows the duration of the next upcoming period. Returns 'Unknown' only when no periods are configured.",
"usage_tips": "For display: Use the state value (hours) in dashboards. For automations: Use `period_duration_minutes` attribute to decide whether to wait out the peak or proceed (e.g., 'If period_duration_minutes <= 60, pause operations')."
"description": "Total length of current or next peak price period in minutes",
"long_description": "Shows how long the peak price period lasts in total. During an active period, shows the duration of the current period. When no period is active, shows the duration of the next upcoming period. Returns 'Unknown' only when no periods are configured.",
"usage_tips": "Useful for planning: 'The next expensive period lasts 60 minutes' or 'Current peak is 90 minutes long'. Combine with remaining_minutes to decide whether to wait out the peak or proceed with operations."
},
"peak_price_remaining_minutes": {
"description": "Time remaining in current peak price period",
"long_description": "Shows how much time is left in the current peak price period. The state displays in hours (e.g., 1.0 h) for easy reading, while the `remaining_minutes` attribute provides minutes (e.g., 60) for automation logic. Returns 0 when no period is active. Updates every minute. Check binary_sensor.peak_price_period to see if a period is currently active.",
"usage_tips": "For automations: Use `remaining_minutes` attribute like 'If remaining_minutes > 60, cancel deferred charging session'. Value 0 makes it easy to distinguish active (value > 0) from inactive (value = 0) periods."
"description": "Minutes remaining in current peak price period (0 when inactive)",
"long_description": "Shows how many minutes are left in the current peak price period. Returns 0 when no period is active. Updates every minute. Check binary_sensor.peak_price_period to see if a period is currently active.",
"usage_tips": "Use in automations: 'If remaining_minutes > 60, cancel deferred charging session'. Value 0 makes it easy to distinguish active (value > 0) from inactive (value = 0) periods."
},
"peak_price_progress": {
"description": "Progress through current peak price period (0% when inactive)",
@ -372,9 +359,9 @@
"usage_tips": "Always useful for planning: 'Next expensive period starts in 2 hours'. Automation: 'When next start time is in 30 minutes, reduce heating temperature preemptively'."
},
"peak_price_next_in_minutes": {
"description": "Time until next peak price period starts",
"long_description": "Shows how long until the next peak price period starts. The state displays in hours (e.g., 0.5 h) for dashboards, while the `next_in_minutes` attribute provides minutes (e.g., 30) for automation conditions. During an active period, shows time until the period AFTER the current one. Returns 0 during brief transition moments. Updates every minute.",
"usage_tips": "For automations: Use `next_in_minutes` attribute like 'If next_in_minutes > 0 AND next_in_minutes < 10, complete current charging cycle now before prices increase'."
"description": "Minutes until next peak price period starts (0 when in transition)",
"long_description": "Shows minutes until the next peak price period starts. During an active period, shows time until the period AFTER the current one. Returns 0 during brief transition moments. Updates every minute.",
"usage_tips": "Pre-emptive automation: 'If next_in_minutes > 0 AND next_in_minutes < 10, complete current charging cycle now before prices increase'."
},
"home_type": {
"description": "Type of home (apartment, house, etc.)",
@ -445,16 +432,6 @@
"description": "Status of your Tibber subscription",
"long_description": "Shows whether your Tibber subscription is currently running, has ended, or is pending activation. A status of 'running' means you're actively receiving electricity through Tibber.",
"usage_tips": "Use this to monitor your subscription status. Set up alerts if status changes from 'running' to ensure uninterrupted service."
},
"chart_data_export": {
"description": "Data export for dashboard integrations",
"long_description": "This binary sensor calls the get_chartdata service with your configured YAML parameters and exposes the result as entity attributes. The state is 'on' when the service call succeeds and data is available, 'off' when the call fails or no configuration is set. Perfect for dashboard integrations like ApexCharts that need to read price data from entity attributes.",
"usage_tips": "Configure the YAML parameters in the integration options to match your get_chartdata service call. The sensor will automatically refresh when price data updates (typically after midnight and when tomorrow's data arrives). Access the service response data directly from the entity's attributes - the structure matches exactly what get_chartdata returns."
},
"chart_metadata": {
"description": "Lightweight metadata for chart configuration",
"long_description": "Provides essential chart configuration values as sensor attributes. Useful for any chart card that needs Y-axis bounds. The sensor calls get_chartdata with metadata-only mode (no data processing) and extracts: yaxis_min, yaxis_max (suggested Y-axis range for optimal scaling). The state reflects the service call result: 'ready' when successful, 'error' on failure, 'pending' during initialization.",
"usage_tips": "Configure via configuration.yaml under tibber_prices.chart_metadata_config (optional: day, subunit_currency, resolution). The sensor automatically refreshes when price data updates. Access metadata from attributes: yaxis_min, yaxis_max. Use with config-template-card or any tool that reads entity attributes - perfect for dynamic chart configuration without manual calculations."
}
},
"binary_sensor": {
@ -487,80 +464,11 @@
"description": "Whether realtime consumption monitoring is active",
"long_description": "Indicates if realtime electricity consumption monitoring is enabled and active for your Tibber home. This requires compatible metering hardware (e.g., Tibber Pulse) and an active subscription.",
"usage_tips": "Use this to verify that realtime consumption data is available. Enable notifications if this changes to 'off' unexpectedly, indicating potential hardware or connectivity issues."
}
},
"number": {
"best_price_flex_override": {
"description": "Maximum above the daily minimum price that intervals can be and still qualify as 'best price'. Recommended: 15-20 with relaxation enabled (default), or 25-35 without relaxation. Maximum: 50 (hard cap for reliable period detection).",
"long_description": "When this entity is enabled, its value overrides the 'Flexibility' setting from the options flow for best price period calculations.",
"usage_tips": "Enable this entity to dynamically adjust best price detection via automations. Higher values create longer periods, lower values are stricter."
},
"best_price_min_distance_override": {
"description": "Ensures periods are significantly cheaper than the daily average, not just marginally below it. This filters out noise and prevents marking slightly-below-average periods as 'best price' on days with flat prices. Higher values = stricter filtering (only truly cheap periods qualify).",
"long_description": "When this entity is enabled, its value overrides the 'Minimum Distance' setting from the options flow for best price period calculations.",
"usage_tips": "Use in automations to adjust how much better than average the best price periods must be. Higher values require prices to be further below average."
},
"best_price_min_period_length_override": {
"description": "Minimum duration for a period to be considered as 'best price'. Longer periods are more practical for running appliances like dishwashers or heat pumps. Best price periods require 60 minutes minimum (vs. 30 minutes for peak price warnings) because they should provide meaningful time windows for consumption planning.",
"long_description": "When this entity is enabled, its value overrides the 'Minimum Period Length' setting from the options flow for best price period calculations.",
"usage_tips": "Increase when your appliances need longer uninterrupted run times (e.g., washing machines, dishwashers)."
},
"best_price_min_periods_override": {
"description": "Minimum number of best price periods to aim for per day. Filters will be relaxed step-by-step to try achieving this count. Only active when 'Achieve Minimum Count' is enabled.",
"long_description": "When this entity is enabled, its value overrides the 'Minimum Periods' setting from the options flow for best price period calculations.",
"usage_tips": "Adjust dynamically based on how many times per day you need cheap electricity windows."
},
"best_price_relaxation_attempts_override": {
"description": "How many flex levels (attempts) to try before giving up. Each attempt runs all filter combinations at the new flex level. More attempts increase the chance of finding additional periods at the cost of longer processing time.",
"long_description": "When this entity is enabled, its value overrides the 'Relaxation Attempts' setting from the options flow for best price period calculations.",
"usage_tips": "Increase when periods are hard to find. Decrease for stricter price filtering."
},
"best_price_gap_count_override": {
"description": "Maximum number of consecutive intervals allowed that deviate by exactly one level step from the required level. This prevents periods from being split by occasional level deviations. Gap tolerance requires periods ≥90 minutes (6 intervals) to detect outliers effectively.",
"long_description": "When this entity is enabled, its value overrides the 'Gap Tolerance' setting from the options flow for best price period calculations.",
"usage_tips": "Increase to allow longer periods with occasional price spikes. Keep low for stricter continuous cheap periods."
},
"peak_price_flex_override": {
"description": "Maximum below the daily maximum price that intervals can be and still qualify as 'peak price'. Recommended: -15 to -20 with relaxation enabled (default), or -25 to -35 without relaxation. Maximum: -50 (hard cap for reliable period detection). Note: Negative values indicate distance below maximum.",
"long_description": "When this entity is enabled, its value overrides the 'Flexibility' setting from the options flow for peak price period calculations.",
"usage_tips": "Enable this entity to dynamically adjust peak price detection via automations. Higher values create longer peak periods."
},
"peak_price_min_distance_override": {
"description": "Ensures periods are significantly more expensive than the daily average, not just marginally above it. This filters out noise and prevents marking slightly-above-average periods as 'peak price' on days with flat prices. Higher values = stricter filtering (only truly expensive periods qualify).",
"long_description": "When this entity is enabled, its value overrides the 'Minimum Distance' setting from the options flow for peak price period calculations.",
"usage_tips": "Use in automations to adjust how much higher than average the peak price periods must be."
},
"peak_price_min_period_length_override": {
"description": "Minimum duration for a period to be considered as 'peak price'. Peak price warnings are allowed for shorter periods (30 minutes minimum vs. 60 minutes for best price) because brief expensive spikes are worth alerting about, even if they're too short for consumption planning.",
"long_description": "When this entity is enabled, its value overrides the 'Minimum Period Length' setting from the options flow for peak price period calculations.",
"usage_tips": "Increase to filter out brief price spikes, focusing on sustained expensive periods."
},
"peak_price_min_periods_override": {
"description": "Minimum number of peak price periods to aim for per day. Filters will be relaxed step-by-step to try achieving this count. Only active when 'Achieve Minimum Count' is enabled.",
"long_description": "When this entity is enabled, its value overrides the 'Minimum Periods' setting from the options flow for peak price period calculations.",
"usage_tips": "Adjust based on how many peak periods you want to identify and avoid."
},
"peak_price_relaxation_attempts_override": {
"description": "How many flex levels (attempts) to try before giving up. Each attempt runs all filter combinations at the new flex level. More attempts increase the chance of finding additional peak periods at the cost of longer processing time.",
"long_description": "When this entity is enabled, its value overrides the 'Relaxation Attempts' setting from the options flow for peak price period calculations.",
"usage_tips": "Increase when peak periods are hard to detect. Decrease for stricter peak price filtering."
},
"peak_price_gap_count_override": {
"description": "Maximum number of consecutive intervals allowed that deviate by exactly one level step from the required level. This prevents periods from being split by occasional level deviations. Gap tolerance requires periods ≥90 minutes (6 intervals) to detect outliers effectively.",
"long_description": "When this entity is enabled, its value overrides the 'Gap Tolerance' setting from the options flow for peak price period calculations.",
"usage_tips": "Increase to identify sustained expensive periods with brief dips. Keep low for stricter continuous peak detection."
}
},
"switch": {
"best_price_enable_relaxation_override": {
"description": "When enabled, filters will be gradually relaxed if not enough periods are found. This attempts to reach the desired minimum number of periods, which may include less optimal time windows as best-price periods.",
"long_description": "When this entity is enabled, its value overrides the 'Achieve Minimum Count' setting from the options flow for best price period calculations.",
"usage_tips": "Turn OFF to disable relaxation and use strict filtering only. Turn ON to allow the algorithm to relax criteria to find more periods."
},
"peak_price_enable_relaxation_override": {
"description": "When enabled, filters will be gradually relaxed if not enough periods are found. This attempts to reach the desired minimum number of periods to ensure you're warned about expensive periods even on days with unusual price patterns.",
"long_description": "When this entity is enabled, its value overrides the 'Achieve Minimum Count' setting from the options flow for peak price period calculations.",
"usage_tips": "Turn OFF to disable relaxation and use strict filtering only. Turn ON to allow the algorithm to relax criteria to find more peak periods."
"chart_data_export": {
"description": "Data export for dashboard integrations",
"long_description": "This binary sensor calls the get_chartdata service with your configured YAML parameters and exposes the result as entity attributes. The state is 'on' when the service call succeeds and data is available, 'off' when the call fails or no configuration is set. Perfect for dashboard integrations like ApexCharts that need to read price data from entity attributes.",
"usage_tips": "Configure the YAML parameters in the integration options to match your get_chartdata service call. The sensor will automatically refresh when price data updates (typically after midnight and when tomorrow's data arrives). Access the service response data directly from the entity's attributes - the structure matches exactly what get_chartdata returns."
}
},
"home_types": {
@ -569,15 +477,5 @@
"HOUSE": "House",
"COTTAGE": "Cottage"
},
"time_units": {
"day": "{count} day",
"days": "{count} days",
"hour": "{count} hour",
"hours": "{count} hours",
"minute": "{count} minute",
"minutes": "{count} minutes",
"ago": "{parts} ago",
"now": "now"
},
"attribution": "Data provided by Tibber"
}

View file

@ -1,20 +1,7 @@
{
"apexcharts": {
"title_rating_level": "Prisfaser dagsfremdrift",
"title_level": "Prisnivå",
"hourly_suffix": "(Ø per time)",
"best_price_period_name": "Beste prisperiode",
"peak_price_period_name": "Toppprisperiode",
"notification": {
"metadata_sensor_unavailable": {
"title": "Tibber Prices: ApexCharts YAML generert med begrenset funksjonalitet",
"message": "Du har nettopp generert en ApexCharts-kort-konfigurasjon via Utviklerverktøy. Diagram-metadata-sensoren er deaktivert, så den genererte YAML-en vil bare vise **grunnleggende funksjonalitet** (auto-skalering, fast gradient på 50%).\n\n**For full funksjonalitet** (optimert skalering, dynamiske gradientfarger):\n1. [Åpne Tibber Prices-integrasjonen](https://my.home-assistant.io/redirect/integration/?domain=tibber_prices)\n2. Aktiver 'Chart Metadata'-sensoren\n3. **Generer YAML-en på nytt** via Utviklerverktøy\n4. **Erstatt den gamle YAML-en** i dashbordet ditt med den nye versjonen\n\n⚠ Det er ikke nok å bare aktivere sensoren - du må regenerere og erstatte YAML-koden!"
},
"missing_cards": {
"title": "Tibber Prices: ApexCharts YAML kan ikke brukes",
"message": "Du har nettopp generert en ApexCharts-kort-konfigurasjon via Utviklerverktøy, men den genererte YAML-en **vil ikke fungere** fordi nødvendige tilpassede kort mangler.\n\n**Manglende kort:**\n{cards}\n\n**For å bruke den genererte YAML-en:**\n1. Klikk på lenkene ovenfor for å installere de manglende kortene fra HACS\n2. Start Home Assistant på nytt (noen ganger nødvendig)\n3. **Generer YAML-en på nytt** via Utviklerverktøy\n4. Legg til YAML-en i dashbordet ditt\n\n⚠ Den nåværende YAML-koden vil ikke fungere før alle kort er installert!"
}
}
"title_rating_level": "Prisfaser daglig fremgang",
"title_level": "Prisnivå"
},
"sensor": {
"current_interval_price": {
@ -22,7 +9,7 @@
"long_description": "Viser nåværende pris per kWh fra ditt Tibber-abonnement",
"usage_tips": "Bruk dette til å spore priser eller lage automatiseringer som kjører når strøm er billig"
},
"current_interval_price_base": {
"current_interval_price_major": {
"description": "Nåværende elektrisitetspris i hovedvaluta (EUR/kWh, NOK/kWh, osv.) for Energi-dashboard",
"long_description": "Viser nåværende pris per kWh i hovedvalutaenheter (f.eks. EUR/kWh i stedet for ct/kWh, NOK/kWh i stedet for øre/kWh). Denne sensoren er spesielt designet for bruk med Home Assistants Energi-dashboard, som krever priser i standard valutaenheter.",
"usage_tips": "Bruk denne sensoren når du konfigurerer Energi-dashboardet under Innstillinger → Dashbord → Energi. Velg denne sensoren som 'Entitet med nåværende pris' for automatisk å beregne energikostnadene. Energi-dashboardet multipliserer energiforbruket ditt (kWh) med denne prisen for å vise totale kostnader."
@ -58,9 +45,9 @@
"usage_tips": "Bruk dette til å unngå å kjøre apparater i toppristider"
},
"average_price_today": {
"description": "Typisk elektrisitetspris i dag per kWh (konfigurerbart visningsformat)",
"long_description": "Viser prisen per kWh for gjeldende dag fra ditt Tibber-abonnement. **Som standard viser statusen medianen** (motstandsdyktig mot ekstreme prisspiss, viser typisk prisnivå). Du kan endre dette i integrasjonsinnstillingene for å vise det aritmetiske gjennomsnittet i stedet. Den alternative verdien er tilgjengelig som attributt.",
"usage_tips": "Bruk dette som baseline for å sammenligne nåværende priser. For beregninger bruk: {{ state_attr('sensor.average_price_today', 'price_mean') }}"
"description": "Den gjennomsnittlige elektrisitetsprisen i dag per kWh",
"long_description": "Viser gjennomsnittsprisen per kWh for gjeldende dag fra ditt Tibber-abonnement",
"usage_tips": "Bruk dette som en baseline for å sammenligne nåværende priser"
},
"lowest_price_tomorrow": {
"description": "Den laveste elektrisitetsprisen i morgen per kWh",
@ -73,9 +60,9 @@
"usage_tips": "Bruk dette til å unngå å kjøre apparater i morgendagens toppristider. Nyttig for å planlegge rundt dyre perioder."
},
"average_price_tomorrow": {
"description": "Typisk elektrisitetspris i morgen per kWh (konfigurerbart visningsformat)",
"long_description": "Viser prisen per kWh for morgendagen fra ditt Tibber-abonnement. **Som standard viser statusen medianen** (motstandsdyktig mot ekstreme prisspiss). Du kan endre dette i integrasjonsinnstillingene for å vise det aritmetiske gjennomsnittet i stedet. Den alternative verdien er tilgjengelig som attributt. Denne sensoren blir utilgjengelig inntil morgendagens data er publisert av Tibber (vanligvis rundt 13:00-14:00 CET).",
"usage_tips": "Bruk dette som baseline for å sammenligne morgendagens priser og planlegge forbruk. Sammenlign med dagens median for å se om morgendagen vil være mer eller mindre dyr totalt sett."
"description": "Den gjennomsnittlige elektrisitetsprisen i morgen per kWh",
"long_description": "Viser gjennomsnittsprisen per kWh for morgendagen fra ditt Tibber-abonnement. Denne sensoren blir utilgjengelig inntil morgendagens data er publisert av Tibber (vanligvis rundt 13:00-14:00 CET).",
"usage_tips": "Bruk dette som en baseline for å sammenligne morgendagens priser og planlegge forbruk. Sammenlign med dagens gjennomsnitt for å se om morgendagen vil være mer eller mindre dyr totalt sett."
},
"yesterday_price_level": {
"description": "Aggregert prisnivå for i går",
@ -108,14 +95,14 @@
"usage_tips": "Bruk dette for å planlegge morgendagens energiforbruk basert på dine personlige pristerskelverdier. Sammenlign med i dag for å bestemme om du skal flytte forbruk til i morgen eller bruke energi i dag."
},
"trailing_price_average": {
"description": "Typisk elektrisitetspris for de siste 24 timene per kWh (konfigurerbart visningsformat)",
"long_description": "Viser prisen per kWh beregnet fra de siste 24 timene. **Som standard viser statusen medianen** (motstandsdyktig mot ekstreme prisspiss, viser typisk prisnivå). Du kan endre dette i integrasjonsinnstillingene for å vise det aritmetiske gjennomsnittet i stedet. Den alternative verdien er tilgjengelig som attributt. Oppdateres hvert 15. minutt.",
"usage_tips": "Bruk statusverdien for å se det typiske nåværende prisnivået. For kostnadsberegninger bruk: {{ state_attr('sensor.trailing_price_average', 'price_mean') }}"
"description": "Den gjennomsnittlige elektrisitetsprisen for de siste 24 timene per kWh",
"long_description": "Viser gjennomsnittsprisen per kWh beregnet fra de siste 24 timene (glidende gjennomsnitt) fra ditt Tibber-abonnement. Dette gir et rullende gjennomsnitt som oppdateres hvert 15. minutt basert på historiske data.",
"usage_tips": "Bruk dette til å sammenligne nåværende priser mot nylige trender. En nåværende pris betydelig over dette gjennomsnittet kan indikere et godt tidspunkt å redusere forbruket."
},
"leading_price_average": {
"description": "Typisk elektrisitetspris for de neste 24 timene per kWh (konfigurerbart visningsformat)",
"long_description": "Viser prisen per kWh beregnet fra de neste 24 timene. **Som standard viser statusen medianen** (motstandsdyktig mot ekstreme prisspiss, viser forventet prisnivå). Du kan endre dette i integrasjonsinnstillingene for å vise det aritmetiske gjennomsnittet i stedet. Den alternative verdien er tilgjengelig som attributt.",
"usage_tips": "Bruk statusverdien for å se det typiske kommende prisnivået. For kostnadsberegninger bruk: {{ state_attr('sensor.leading_price_average', 'price_mean') }}"
"description": "Den gjennomsnittlige elektrisitetsprisen for de neste 24 timene per kWh",
"long_description": "Viser gjennomsnittsprisen per kWh beregnet fra de neste 24 timene (fremtidsrettet gjennomsnitt) fra ditt Tibber-abonnement. Dette gir et fremtidsrettet gjennomsnitt basert på tilgjengelige prognosedata.",
"usage_tips": "Bruk dette til å planlegge energibruk. Hvis nåværende pris er under det fremtidsrettede gjennomsnittet, kan det være et godt tidspunkt å kjøre energikrevende apparater."
},
"trailing_price_min": {
"description": "Den minste elektrisitetsprisen for de siste 24 timene per kWh",
@ -292,74 +279,64 @@
"long_description": "Viser tidsstempelet for siste tilgjengelige prisdataintervall fra ditt Tibber-abonnement"
},
"today_volatility": {
"description": "Hvor mye strømprisene endrer seg i dag",
"long_description": "Viser om dagens priser er stabile eller har store svingninger. Lav volatilitet betyr ganske jevne priser timing betyr lite. Høy volatilitet betyr tydelige prisforskjeller gjennom dagen en god sjanse til å flytte forbruk til billigere perioder. `price_coefficient_variation_%` viser prosentverdien, `price_spread` viser den absolutte prisspennet.",
"usage_tips": "Bruk dette for å avgjøre om optimalisering er verdt innsatsen. Ved lav volatilitet kan du kjøre enheter når som helst. Ved høy volatilitet sparer du merkbart ved å følge Best Price-perioder."
"description": "Prisvolatilitetsklassifisering for i dag",
"long_description": "Viser hvor mye strømprisene varierer gjennom dagen basert på spredningen (forskjellen mellom høyeste og laveste pris). Klassifisering: LOW = spredning < 5øre, MODERATE = 5-15øre, HIGH = 15-30øre, VERY HIGH = >30øre.",
"usage_tips": "Bruk dette til å bestemme om prisbasert optimalisering er verdt det. For eksempel, med et balkongbatteri som har 15% effektivitetstap, er optimalisering kun meningsfull når volatiliteten er minst MODERATE. Opprett automatiseringer som sjekker volatilitet før planlegging av lade-/utladingssykluser."
},
"tomorrow_volatility": {
"description": "Hvor mye strømprisene vil endre seg i morgen",
"long_description": "Viser om prisene i morgen blir stabile eller får store svingninger. Tilgjengelig når morgendagens data er publisert (vanligvis 13:0014:00 CET). Lav volatilitet betyr jevne priser timing er ikke kritisk. Høy volatilitet betyr tydelige prisforskjeller gjennom dagen en god mulighet til å planlegge energikrevende oppgaver. `price_coefficient_variation_%` viser prosentverdien, `price_spread` viser den absolutte prisspennet.",
"usage_tips": "Bruk dette til å planlegge morgendagens forbruk. Høy volatilitet? Planlegg fleksible laster i Best Price-perioder. Lav volatilitet? Kjør enheter når det passer deg."
"description": "Prisvolatilitetsklassifisering for i morgen",
"long_description": "Viser hvor mye strømprisene vil variere gjennom morgendagen basert på spredningen (forskjellen mellom høyeste og laveste pris). Blir utilgjengelig til morgendagens data er publisert (typisk 13:00-14:00 CET).",
"usage_tips": "Bruk dette til forhåndsplanlegging av morgendagens energiforbruk. Hvis morgendagen har HIGH eller VERY HIGH volatilitet, er det verdt å optimalisere tidspunktet for energiforbruk. Hvis LOW, kan du kjøre enheter når som helst uten betydelige kostnadsforskjeller."
},
"next_24h_volatility": {
"description": "Hvor mye prisene endrer seg de neste 24 timene",
"long_description": "Viser prisvolatilitet for et rullerende 24-timers vindu fra nå (oppdateres hvert 15. minutt). Lav volatilitet betyr jevne priser. Høy volatilitet betyr merkbare prissvingninger og mulighet for optimalisering. I motsetning til i dag/i morgen-sensorer krysser denne daggrenser og gir en kontinuerlig fremoverskuende vurdering. `price_coefficient_variation_%` viser prosentverdien, `price_spread` viser den absolutte prisspennet.",
"usage_tips": "Best for beslutninger i sanntid. Bruk når du planlegger batterilading eller andre fleksible laster som kan gå over midnatt. Gir et konsistent 24t-bilde uavhengig av kalenderdag."
"description": "Prisvolatilitetsklassifisering for de rullerende neste 24 timene",
"long_description": "Viser hvor mye strømprisene varierer i de neste 24 timene fra nå (rullerende vindu). Dette krysser daggrenser og oppdateres hvert 15. minutt, og gir en fremoverskuende volatilitetsvurdering uavhengig av kalenderdager.",
"usage_tips": "Beste sensor for sanntids optimaliseringsbeslutninger. I motsetning til dagens/morgendagens sensorer som bytter ved midnatt, gir denne kontinuerlig 24t volatilitetsvurdering. Bruk til batteriladingsstrategier som spenner over daggrenser."
},
"today_tomorrow_volatility": {
"description": "Kombinert prisvolatilitet for i dag og i morgen",
"long_description": "Viser samlet volatilitet når i dag og i morgen sees sammen (når morgendata er tilgjengelig). Viser om det finnes klare prisforskjeller over dagsgrensen. Faller tilbake til kun i dag hvis morgendata mangler. Nyttig for flerdagers optimalisering. `price_coefficient_variation_%` viser prosentverdien, `price_spread` viser den absolutte prisspennet.",
"usage_tips": "Bruk for oppgaver som går over flere dager. Sjekk om prisforskjellene er store nok til å planlegge etter. De enkelte dagssensorene viser bidrag per dag om du trenger mer detalj."
"description": "Kombinert prisvolatilitetsklassifisering for i dag og i morgen",
"long_description": "Viser volatilitet på tvers av både i dag og i morgen kombinert (når morgendagens data er tilgjengelig). Gir en utvidet oversikt over prisvariasjoner som spenner over opptil 48 timer. Faller tilbake til kun i dag når morgendagens data ikke er tilgjengelig ennå.",
"usage_tips": "Bruk dette til flerørs planlegging og for å forstå om prismuligheter eksisterer på tvers av daggrensen. Attributtene 'today_volatility' og 'tomorrow_volatility' viser individuelle dagsbidrag. Nyttig for planlegging av ladesesjoner som kan strekke seg over midnatt."
},
"data_lifecycle_status": {
"description": "Gjeldende tilstand for prisdatalivssyklus og hurtigbufring",
"long_description": "Viser om integrasjonen bruker hurtigbufrede data eller ferske data fra API-et. Viser gjeldende livssyklustilstand: 'cached' (bruker lagrede data), 'fresh' (nettopp hentet fra API), 'refreshing' (henter for øyeblikket), 'searching_tomorrow' (søker aktivt etter morgendagens data etter 13:00), 'turnover_pending' (innen 15 minutter før midnatt, 23:45-00:00), eller 'error' (henting mislyktes). Inkluderer omfattende attributter som cache-alder, neste API-spørring, datafullstendighet og API-anropsstatistikk.",
"usage_tips": "Bruk denne diagnosesensoren for å forstå dataferskhet og API-anropsmønstre. Sjekk 'cache_age'-attributtet for å se hvor gamle de nåværende dataene er. Overvåk 'next_api_poll' for å vite når neste oppdatering er planlagt. Bruk 'data_completeness' for å se om data for i går/i dag/i morgen er tilgjengelig. 'api_calls_today'-telleren hjelper med å spore API-bruk. Perfekt for feilsøking eller forståelse av integrasjonens oppførsel."
"price_forecast": {
"description": "Prognose for kommende elektrisitetspriser",
"long_description": "Viser kommende elektrisitetspriser for fremtidige intervaller i et format som er enkelt å bruke i dashboards",
"usage_tips": "Bruk denne entitetens attributter til å vise kommende priser i diagrammer eller tilpassede kort. Få tilgang til enten 'intervals' for alle fremtidige intervaller eller 'hours' for timesammendrag."
},
"best_price_end_time": {
"description": "Total lengde på nåværende eller neste billigperiode (state i timer, attributt i minutter)",
"long_description": "Viser hvor lenge billigperioden varer. State bruker timer (desimal) for lesbar UI; attributtet `period_duration_minutes` beholder avrundede minutter for automasjoner. Aktiv → varighet for gjeldende periode, ellers neste.",
"usage_tips": "UI kan vise 1,5 t mens `period_duration_minutes` = 90 for automasjoner."
},
"best_price_period_duration": {
"description": "Lengde på gjeldende/neste billigperiode",
"long_description": "Total varighet av gjeldende eller neste billigperiode. State vises i timer (f.eks. 1,5 t) for enkel lesing i UI, mens attributtet `period_duration_minutes` gir samme verdi i minutter (f.eks. 90) for automasjoner. Denne verdien representerer den **fulle planlagte varigheten** av perioden og er konstant gjennom hele perioden, selv om gjenværende tid (remaining_minutes) reduseres.",
"usage_tips": "Kombiner med remaining_minutes for å beregne når langvarige enheter skal stoppes: Perioden startet for `period_duration_minutes - remaining_minutes` minutter siden. Dette attributtet støtter energioptimeringsstrategier ved å hjelpe til med å planlegge høyforbruksaktiviteter innenfor billige perioder."
"description": "Når gjeldende eller neste billigperiode slutter",
"long_description": "Viser sluttidspunktet for gjeldende billigperiode når aktiv, eller slutten av neste periode når ingen periode er aktiv. Viser alltid en nyttig tidsreferanse for planlegging. Returnerer 'Ukjent' bare når ingen perioder er konfigurert.",
"usage_tips": "Bruk dette til å vise en nedtelling som 'Billigperiode slutter om 2 timer' (når aktiv) eller 'Neste billigperiode slutter kl 14:00' (når inaktiv). Home Assistant viser automatisk relativ tid for tidsstempelsensorer."
},
"best_price_remaining_minutes": {
"description": "Gjenværende tid i gjeldende billigperiode",
"long_description": "Viser hvor mye tid som gjenstår i gjeldende billigperiode. State vises i timer (f.eks. 0,75 t) for enkel lesing i dashboards, mens attributtet `remaining_minutes` gir samme tid i minutter (f.eks. 45) for automasjonsbetingelser. **Nedtellingstimer**: Denne verdien reduseres hvert minutt under en aktiv periode. Returnerer 0 når ingen billigperiode er aktiv. Oppdateres hvert minutt.",
"usage_tips": "For automasjoner: Bruk attributtet `remaining_minutes` som 'Hvis remaining_minutes > 60, start oppvaskmaskinen nå (nok tid til å fullføre)' eller 'Hvis remaining_minutes < 15, fullfør gjeldende syklus snart'. UI viser brukervennlige timer (f.eks. 1,25 t). Verdi 0 indikerer ingen aktiv billigperiode."
"description": "Gjenværende minutter i gjeldende billigperiode (0 når inaktiv)",
"long_description": "Viser hvor mange minutter som er igjen i gjeldende billigperiode. Returnerer 0 når ingen periode er aktiv. Oppdateres hvert minutt. Sjekk binary_sensor.best_price_period for å se om en periode er aktiv.",
"usage_tips": "Perfekt for automatiseringer: 'Hvis remaining_minutes > 0 OG remaining_minutes < 30, start vaskemaskin nå'. Verdien 0 gjør det enkelt å sjekke om en periode er aktiv (verdi > 0) eller ikke (verdi = 0)."
},
"best_price_progress": {
"description": "Fremdrift gjennom gjeldende billigperiode (0% når inaktiv)",
"long_description": "Viser fremdrift gjennom gjeldende billigperiode som 0-100%. Returnerer 0% når ingen periode er aktiv. Oppdateres hvert minutt. 0% betyr perioden nettopp startet, 100% betyr den slutter snart.",
"usage_tips": "Flott for visuelle fremgangsindikatorer. Bruk i automatiseringer: 'Hvis progress > 0 OG progress > 75, send varsel om at billigperioden snart slutter'. Verdi 0 indikerer ingen aktiv periode."
"long_description": "Viser fremdrift gjennom gjeldende billigperiode som 0-100%. Returnerer 0% når ingen periode er aktiv. Oppdateres hvert minutt. 0% betyr periode nettopp startet, 100% betyr den snart slutter.",
"usage_tips": "Flott for visuelle fremdriftslinjer. Bruk i automatiseringer: 'Hvis progress > 0 OG progress > 75, send varsel om at billigperiode snart slutter'. Verdi 0 indikerer ingen aktiv periode."
},
"best_price_next_start_time": {
"description": "Total lengde på nåværende eller neste dyr-periode (state i timer, attributt i minutter)",
"long_description": "Viser hvor lenge den dyre perioden varer. State bruker timer (desimal) for UI; attributtet `period_duration_minutes` beholder avrundede minutter for automasjoner. Aktiv → varighet for gjeldende periode, ellers neste.",
"usage_tips": "UI kan vise 0,75 t mens `period_duration_minutes` = 45 for automasjoner."
"description": "Når neste billigperiode starter",
"long_description": "Viser når neste kommende billigperiode starter. Under en aktiv periode viser dette starten av NESTE periode etter den gjeldende. Returnerer 'Ukjent' bare når ingen fremtidige perioder er konfigurert.",
"usage_tips": "Alltid nyttig for planlegging: 'Neste billigperiode starter om 3 timer' (enten du er i en periode nå eller ikke). Kombiner med automatiseringer: 'Når neste starttid er om 10 minutter, send varsel for å forberede vaskemaskin'."
},
"best_price_next_in_minutes": {
"description": "Tid til neste billigperiode",
"long_description": "Viser hvor lenge til neste billigperiode. State vises i timer (f.eks. 2,25 t) for dashboards, mens attributtet `next_in_minutes` gir minutter (f.eks. 135) for automasjonsbetingelser. Under en aktiv periode viser dette tiden til perioden ETTER den gjeldende. Returnerer 0 under korte overgangsmomenter. Oppdateres hvert minutt.",
"usage_tips": "For automasjoner: Bruk attributtet `next_in_minutes` som 'Hvis next_in_minutes > 0 OG next_in_minutes < 15, vent før start av oppvaskmaskin'. Verdi > 0 indikerer alltid at en fremtidig periode er planlagt."
"description": "Minutter til neste billigperiode starter (0 ved overgang)",
"long_description": "Viser minutter til neste billigperiode starter. Under en aktiv periode viser dette tiden til perioden ETTER den gjeldende. Returnerer 0 under korte overgangsmomenter. Oppdateres hvert minutt.",
"usage_tips": "Perfekt for 'vent til billigperiode' automatiseringer: 'Hvis next_in_minutes > 0 OG next_in_minutes < 15, vent før oppvaskmaskin startes'. Verdi > 0 indikerer alltid at en fremtidig periode er planlagt."
},
"peak_price_end_time": {
"description": "Tid til neste dyr-periode (state i timer, attributt i minutter)",
"long_description": "Viser hvor lenge til neste dyre periode starter. State bruker timer (desimal); attributtet `next_in_minutes` beholder avrundede minutter for automasjoner. Under aktiv periode viser dette tiden til perioden etter den nåværende. 0 i korte overgangsøyeblikk. Oppdateres hvert minutt.",
"usage_tips": "Bruk `next_in_minutes` i automasjoner (f.eks. < 10) mens state er lett å lese i timer."
},
"peak_price_period_duration": {
"description": "Lengde på gjeldende/neste dyr periode",
"long_description": "Total varighet av gjeldende eller neste dyre periode. State vises i timer (f.eks. 1,5 t) for enkel lesing i UI, mens attributtet `period_duration_minutes` gir samme verdi i minutter (f.eks. 90) for automasjoner. Denne verdien representerer den **fulle planlagte varigheten** av perioden og er konstant gjennom hele perioden, selv om gjenværende tid (remaining_minutes) reduseres.",
"usage_tips": "Kombiner med remaining_minutes for å beregne når langvarige enheter skal stoppes: Perioden startet for `period_duration_minutes - remaining_minutes` minutter siden. Dette attributtet støtter energisparingsstrategier ved å hjelpe til med å planlegge høyforbruksaktiviteter utenfor dyre perioder."
"description": "Når gjeldende eller neste dyrperiode slutter",
"long_description": "Viser sluttidspunktet for gjeldende dyrperiode når aktiv, eller slutten av neste periode når ingen periode er aktiv. Viser alltid en nyttig tidsreferanse for planlegging. Returnerer 'Ukjent' bare når ingen perioder er konfigurert.",
"usage_tips": "Bruk dette til å vise 'Dyrperiode slutter om 1 time' (når aktiv) eller 'Neste dyrperiode slutter kl 18:00' (når inaktiv). Kombiner med automatiseringer for å gjenoppta drift etter topp."
},
"peak_price_remaining_minutes": {
"description": "Gjenværende tid i gjeldende dyre periode",
"long_description": "Viser hvor mye tid som gjenstår i gjeldende dyre periode. State vises i timer (f.eks. 0,75 t) for enkel lesing i dashboards, mens attributtet `remaining_minutes` gir samme tid i minutter (f.eks. 45) for automasjonsbetingelser. **Nedtellingstimer**: Denne verdien reduseres hvert minutt under en aktiv periode. Returnerer 0 når ingen dyr periode er aktiv. Oppdateres hvert minutt.",
"usage_tips": "For automasjoner: Bruk attributtet `remaining_minutes` som 'Hvis remaining_minutes > 60, avbryt utsatt ladeøkt' eller 'Hvis remaining_minutes < 15, fortsett normal drift snart'. UI viser brukervennlige timer (f.eks. 1,0 t). Verdi 0 indikerer ingen aktiv dyr periode."
"description": "Gjenværende minutter i gjeldende dyrperiode (0 når inaktiv)",
"long_description": "Viser hvor mange minutter som er igjen i gjeldende dyrperiode. Returnerer 0 når ingen periode er aktiv. Oppdateres hvert minutt. Sjekk binary_sensor.peak_price_period for å se om en periode er aktiv.",
"usage_tips": "Bruk i automatiseringer: 'Hvis remaining_minutes > 60, avbryt utsatt ladeøkt'. Verdi 0 gjør det enkelt å skille mellom aktive (verdi > 0) og inaktive (verdi = 0) perioder."
},
"peak_price_progress": {
"description": "Fremdrift gjennom gjeldende dyrperiode (0% når inaktiv)",
@ -372,9 +349,19 @@
"usage_tips": "Alltid nyttig for planlegging: 'Neste dyrperiode starter om 2 timer'. Automatisering: 'Når neste starttid er om 30 minutter, reduser varmetemperatur forebyggende'."
},
"peak_price_next_in_minutes": {
"description": "Tid til neste dyre periode",
"long_description": "Viser hvor lenge til neste dyre periode starter. State vises i timer (f.eks. 0,5 t) for dashboards, mens attributtet `next_in_minutes` gir minutter (f.eks. 30) for automasjonsbetingelser. Under en aktiv periode viser dette tiden til perioden ETTER den gjeldende. Returnerer 0 under korte overgangsmomenter. Oppdateres hvert minutt.",
"usage_tips": "For automasjoner: Bruk attributtet `next_in_minutes` som 'Hvis next_in_minutes > 0 OG next_in_minutes < 10, fullfør gjeldende ladesyklus nå før prisene øker'. Verdi > 0 indikerer alltid at en fremtidig dyr periode er planlagt."
"description": "Minutter til neste dyrperiode starter (0 ved overgang)",
"long_description": "Viser minutter til neste dyrperiode starter. Under en aktiv periode viser dette tiden til perioden ETTER den gjeldende. Returnerer 0 under korte overgangsmomenter. Oppdateres hvert minutt.",
"usage_tips": "Forebyggende automatisering: 'Hvis next_in_minutes > 0 OG next_in_minutes < 10, fullfør gjeldende ladesyklus nå før prisene øker'."
},
"best_price_period_duration": {
"description": "Total varighet av gjeldende eller neste billigperiode i minutter",
"long_description": "Viser den totale varigheten av billigperioden i minutter. Under en aktiv periode viser dette hele varigheten av gjeldende periode. Når ingen periode er aktiv, viser dette varigheten av neste kommende periode. Eksempel: '90 minutter' for en 1,5-timers periode.",
"usage_tips": "Kombiner med remaining_minutes for å planlegge oppgaver: 'Hvis duration = 120 OG remaining_minutes > 90, start vaskemaskin (nok tid til å fullføre)'. Nyttig for å forstå om perioder er lange nok for strømkrevende oppgaver."
},
"peak_price_period_duration": {
"description": "Total varighet av gjeldende eller neste dyrperiode i minutter",
"long_description": "Viser den totale varigheten av dyrperioden i minutter. Under en aktiv periode viser dette hele varigheten av gjeldende periode. Når ingen periode er aktiv, viser dette varigheten av neste kommende periode. Eksempel: '60 minutter' for en 1-times periode.",
"usage_tips": "Bruk til å planlegge energibesparelsestiltak: 'Hvis duration > 120, reduser varmetemperatur mer aggressivt (lang dyr periode)'. Hjelper med å vurdere hvor mye energiforbruk må reduseres."
},
"home_type": {
"description": "Type bolig (leilighet, hus osv.)",
@ -450,11 +437,6 @@
"description": "Dataeksport for dashboardintegrasjoner",
"long_description": "Denne sensoren kaller get_chartdata-tjenesten med din konfigurerte YAML-konfigurasjon og eksponerer resultatet som entitetsattributter. Status viser 'ready' når data er tilgjengelig, 'error' ved feil, eller 'pending' før første kall. Perfekt for dashboardintegrasjoner som ApexCharts som trenger å lese prisdata fra entitetsattributter.",
"usage_tips": "Konfigurer YAML-parametrene i integrasjonsinnstillingene for å matche get_chartdata-tjenestekallet ditt. Sensoren vil automatisk oppdatere når prisdata oppdateres (typisk etter midnatt og når morgendagens data ankommer). Få tilgang til tjenesteresponsdataene direkte fra entitetens attributter - strukturen matcher nøyaktig det get_chartdata returnerer."
},
"chart_metadata": {
"description": "Lettvekts metadata for diagramkonfigurasjon",
"long_description": "Gir essensielle diagramkonfigurasjonsverdier som sensorattributter. Nyttig for ethvert diagramkort som trenger Y-aksegrenser. Sensoren kaller get_chartdata med kun-metadata-modus (ingen databehandling) og trekker ut: yaxis_min, yaxis_max (foreslått Y-akseområde for optimal skalering). Status reflekterer tjenestekallresultatet: 'ready' ved suksess, 'error' ved feil, 'pending' under initialisering.",
"usage_tips": "Konfigurer via configuration.yaml under tibber_prices.chart_metadata_config (valgfritt: day, subunit_currency, resolution). Sensoren oppdateres automatisk når prisdata endres. Få tilgang til metadata fra attributter: yaxis_min, yaxis_max. Bruk med config-template-card eller ethvert verktøy som leser entitetsattributter - perfekt for dynamisk diagramkonfigurasjon uten manuelle beregninger."
}
},
"binary_sensor": {
@ -487,80 +469,11 @@
"description": "Om sanntidsforbruksovervåking er aktiv",
"long_description": "Indikerer om sanntidsovervåking av strømforbruk er aktivert og aktiv for ditt Tibber-hjem. Dette krever kompatibel målehardware (f.eks. Tibber Pulse) og et aktivt abonnement.",
"usage_tips": "Bruk dette for å bekrefte at sanntidsforbruksdata er tilgjengelig. Aktiver varsler hvis dette endres til 'av' uventet, noe som indikerer potensielle maskinvare- eller tilkoblingsproblemer."
}
},
"number": {
"best_price_flex_override": {
"description": "Maksimal prosent over daglig minimumspris som intervaller kan ha og fortsatt kvalifisere som 'beste pris'. Anbefalt: 15-20 med lemping aktivert (standard), eller 25-35 uten lemping. Maksimum: 50 (tak for pålitelig periodedeteksjon).",
"long_description": "Når denne entiteten er aktivert, overstyrer verdien 'Fleksibilitet'-innstillingen fra alternativer-dialogen for beste pris-periodeberegninger.",
"usage_tips": "Aktiver denne entiteten for å dynamisk justere beste pris-deteksjon via automatiseringer, f.eks. høyere fleksibilitet for kritiske laster eller strengere krav for fleksible apparater."
},
"best_price_min_distance_override": {
"description": "Minimum prosentavstand under daglig gjennomsnitt. Intervaller må være så langt under gjennomsnittet for å kvalifisere som 'beste pris'. Hjelper med å skille ekte lavprisperioder fra gjennomsnittspriser.",
"long_description": "Når denne entiteten er aktivert, overstyrer verdien 'Minimumsavstand'-innstillingen fra alternativer-dialogen for beste pris-periodeberegninger.",
"usage_tips": "Øk verdien for strengere beste pris-kriterier. Reduser hvis for få perioder blir oppdaget."
},
"best_price_min_period_length_override": {
"description": "Minimum periodelengde i 15-minutters intervaller. Perioder kortere enn dette blir ikke rapportert. Eksempel: 2 = minimum 30 minutter.",
"long_description": "Når denne entiteten er aktivert, overstyrer verdien 'Minimum periodelengde'-innstillingen fra alternativer-dialogen for beste pris-periodeberegninger.",
"usage_tips": "Juster til typisk apparatkjøretid: 2 (30 min) for hurtigprogrammer, 4-8 (1-2 timer) for normale sykluser, 8+ for lange ECO-programmer."
},
"best_price_min_periods_override": {
"description": "Minimum antall beste pris-perioder å finne daglig. Når lemping er aktivert, vil systemet automatisk justere kriterier for å oppnå dette antallet.",
"long_description": "Når denne entiteten er aktivert, overstyrer verdien 'Minimum perioder'-innstillingen fra alternativer-dialogen for beste pris-periodeberegninger.",
"usage_tips": "Sett dette til antall tidskritiske oppgaver du har daglig. Eksempel: 2 for to vaskemaskinkjøringer."
},
"best_price_relaxation_attempts_override": {
"description": "Antall forsøk på å gradvis lempe kriteriene for å oppnå minimum periodeantall. Hvert forsøk øker fleksibiliteten med 3 prosent. Ved 0 brukes kun basiskriterier.",
"long_description": "Når denne entiteten er aktivert, overstyrer verdien 'Lemping forsøk'-innstillingen fra alternativer-dialogen for beste pris-periodeberegninger.",
"usage_tips": "Høyere verdier gjør periodedeteksjon mer adaptiv for dager med stabile priser. Sett til 0 for å tvinge strenge kriterier uten lemping."
},
"best_price_gap_count_override": {
"description": "Maksimalt antall dyrere intervaller som kan tillates mellom billige intervaller mens de fortsatt regnes som en sammenhengende periode. Ved 0 må billige intervaller være påfølgende.",
"long_description": "Når denne entiteten er aktivert, overstyrer verdien 'Gaptoleranse'-innstillingen fra alternativer-dialogen for beste pris-periodeberegninger.",
"usage_tips": "Øk dette for apparater med variabel last (f.eks. varmepumper) som kan tåle korte dyrere intervaller. Sett til 0 for kontinuerlige billige perioder."
},
"peak_price_flex_override": {
"description": "Maksimal prosent under daglig maksimumspris som intervaller kan ha og fortsatt kvalifisere som 'topppris'. Samme anbefalinger som for beste pris-fleksibilitet.",
"long_description": "Når denne entiteten er aktivert, overstyrer verdien 'Fleksibilitet'-innstillingen fra alternativer-dialogen for topppris-periodeberegninger.",
"usage_tips": "Bruk dette for å justere topppris-terskelen ved kjøretid for automatiseringer som unngår forbruk under dyre timer."
},
"peak_price_min_distance_override": {
"description": "Minimum prosentavstand over daglig gjennomsnitt. Intervaller må være så langt over gjennomsnittet for å kvalifisere som 'topppris'.",
"long_description": "Når denne entiteten er aktivert, overstyrer verdien 'Minimumsavstand'-innstillingen fra alternativer-dialogen for topppris-periodeberegninger.",
"usage_tips": "Øk verdien for kun å fange ekstreme pristopper. Reduser for å inkludere flere høypristider."
},
"peak_price_min_period_length_override": {
"description": "Minimum periodelengde i 15-minutters intervaller for topppriser. Kortere pristopper rapporteres ikke som perioder.",
"long_description": "Når denne entiteten er aktivert, overstyrer verdien 'Minimum periodelengde'-innstillingen fra alternativer-dialogen for topppris-periodeberegninger.",
"usage_tips": "Kortere verdier fanger korte pristopper. Lengre verdier fokuserer på vedvarende høyprisperioder."
},
"peak_price_min_periods_override": {
"description": "Minimum antall topppris-perioder å finne daglig.",
"long_description": "Når denne entiteten er aktivert, overstyrer verdien 'Minimum perioder'-innstillingen fra alternativer-dialogen for topppris-periodeberegninger.",
"usage_tips": "Sett dette basert på hvor mange høyprisperioder du vil fange per dag for automatiseringer."
},
"peak_price_relaxation_attempts_override": {
"description": "Antall forsøk på å lempe kriteriene for å oppnå minimum antall topppris-perioder.",
"long_description": "Når denne entiteten er aktivert, overstyrer verdien 'Lemping forsøk'-innstillingen fra alternativer-dialogen for topppris-periodeberegninger.",
"usage_tips": "Øk dette hvis ingen perioder blir funnet på dager med stabile priser. Sett til 0 for å tvinge strenge kriterier."
},
"peak_price_gap_count_override": {
"description": "Maksimalt antall billigere intervaller som kan tillates mellom dyre intervaller mens de fortsatt regnes som en topppris-periode.",
"long_description": "Når denne entiteten er aktivert, overstyrer verdien 'Gaptoleranse'-innstillingen fra alternativer-dialogen for topppris-periodeberegninger.",
"usage_tips": "Høyere verdier fanger lengre høyprisperioder selv med korte prisdykk. Sett til 0 for strengt sammenhengende topppriser."
}
},
"switch": {
"best_price_enable_relaxation_override": {
"description": "Når aktivert, lempes kriteriene automatisk for å oppnå minimum periodeantall. Når deaktivert, rapporteres kun perioder som oppfyller strenge kriterier (muligens null perioder på dager med stabile priser).",
"long_description": "Når denne entiteten er aktivert, overstyrer verdien 'Oppnå minimumsantall'-innstillingen fra alternativer-dialogen for beste pris-periodeberegninger.",
"usage_tips": "Aktiver dette for garanterte daglige automatiseringsmuligheter. Deaktiver hvis du kun vil ha virkelig billige perioder, selv om det betyr ingen perioder på noen dager."
},
"peak_price_enable_relaxation_override": {
"description": "Når aktivert, lempes kriteriene automatisk for å oppnå minimum periodeantall. Når deaktivert, rapporteres kun ekte pristopper.",
"long_description": "Når denne entiteten er aktivert, overstyrer verdien 'Oppnå minimumsantall'-innstillingen fra alternativer-dialogen for topppris-periodeberegninger.",
"usage_tips": "Aktiver dette for konsistente topppris-varsler. Deaktiver for kun å fange ekstreme pristopper."
"chart_data_export": {
"description": "Dataeksport for dashboardintegrasjoner",
"long_description": "Denne binærsensoren kaller get_chartdata-tjenesten for å eksportere prisdata i formater som er kompatible med ApexCharts og andre dashboardverktøy. Dataeksporten inkluderer historiske og fremtidsrettede prisdata strukturert for visualisering.",
"usage_tips": "Konfigurer YAML-parametrene i integrasjonsalternativene. Bruk denne sensoren til å trigge dataeksporthendelser for dashboards. Når den slås på, eksporteres data til en fil eller tjeneste som er konfigurert for integrering med ApexCharts eller tilsvarende visualiseringsverktøy."
}
},
"home_types": {
@ -569,15 +482,5 @@
"HOUSE": "Hus",
"COTTAGE": "Hytte"
},
"time_units": {
"day": "{count} dag",
"days": "{count} dager",
"hour": "{count} time",
"hours": "{count} timer",
"minute": "{count} minutt",
"minutes": "{count} minutter",
"ago": "{parts} siden",
"now": "nå"
},
"attribution": "Data levert av Tibber"
}

View file

@ -1,40 +1,27 @@
{
"apexcharts": {
"title_rating_level": "Prijsfasen dagverloop",
"title_level": "Prijsniveau",
"hourly_suffix": "(Ø per uur)",
"best_price_period_name": "Beste prijsperiode",
"peak_price_period_name": "Piekprijsperiode",
"notification": {
"metadata_sensor_unavailable": {
"title": "Tibber Prices: ApexCharts YAML gegenereerd met beperkte functionaliteit",
"message": "Je hebt zojuist een ApexCharts-kaartconfiguratie gegenereerd via Ontwikkelaarstools. De grafiek-metadata-sensor is momenteel uitgeschakeld, dus de gegenereerde YAML toont alleen **basisfunctionaliteit** (auto-schaal as, vaste verloop op 50%).\n\n**Voor volledige functionaliteit** (geoptimaliseerde schaling, dynamische verloopkleuren):\n1. [Open Tibber Prices-integratie](https://my.home-assistant.io/redirect/integration/?domain=tibber_prices)\n2. Schakel de 'Chart Metadata'-sensor in\n3. **Genereer de YAML opnieuw** via Ontwikkelaarstools\n4. **Vervang de oude YAML** in je dashboard door de nieuwe versie\n\n⚠ Alleen de sensor inschakelen is niet genoeg - je moet de YAML opnieuw genereren en vervangen!"
},
"missing_cards": {
"title": "Tibber Prices: ApexCharts YAML kan niet worden gebruikt",
"message": "Je hebt zojuist een ApexCharts-kaartconfiguratie gegenereerd via Ontwikkelaarstools, maar de gegenereerde YAML **zal niet werken** omdat vereiste aangepaste kaarten ontbreken.\n\n**Ontbrekende kaarten:**\n{cards}\n\n**Om de gegenereerde YAML te gebruiken:**\n1. Klik op de bovenstaande links om de ontbrekende kaarten te installeren vanuit HACS\n2. Herstart Home Assistant (soms nodig)\n3. **Genereer de YAML opnieuw** via Ontwikkelaarstools\n4. Voeg de YAML toe aan je dashboard\n\n⚠ De huidige YAML-code werkt niet totdat alle kaarten zijn geïnstalleerd!"
}
}
"title_rating_level": "Prijsfasen dagelijkse voortgang",
"title_level": "Prijsniveau"
},
"sensor": {
"current_interval_price": {
"description": "De huidige elektriciteitsprijs per kWh",
"long_description": "Toont de huidige prijs per kWh van je Tibber-abonnement",
"long_description": "Toont de huidige prijs per kWh van uw Tibber-abonnement",
"usage_tips": "Gebruik dit om prijzen bij te houden of om automatiseringen te maken die worden uitgevoerd wanneer elektriciteit goedkoop is"
},
"current_interval_price_base": {
"current_interval_price_major": {
"description": "Huidige elektriciteitsprijs in hoofdvaluta (EUR/kWh, NOK/kWh, enz.) voor Energie-dashboard",
"long_description": "Toont de huidige prijs per kWh in hoofdvaluta-eenheden (bijv. EUR/kWh in plaats van ct/kWh, NOK/kWh in plaats van øre/kWh). Deze sensor is speciaal ontworpen voor gebruik met het Energie-dashboard van Home Assistant, dat prijzen in standaard valuta-eenheden vereist.",
"usage_tips": "Gebruik deze sensor bij het configureren van het Energie-dashboard onder Instellingen → Dashboards → Energie. Selecteer deze sensor als 'Entiteit met huidige prijs' om automatisch je energiekosten te berekenen. Het Energie-dashboard vermenigvuldigt je energieverbruik (kWh) met deze prijs om totale kosten weer te geven."
},
"next_interval_price": {
"description": "De volgende interval elektriciteitsprijs per kWh",
"long_description": "Toont de prijs voor het volgende 15-minuten interval van je Tibber-abonnement",
"usage_tips": "Gebruik dit om je voor te bereiden op aanstaande prijswijzigingen of om apparaten te plannen om tijdens goedkopere intervallen te draaien"
"long_description": "Toont de prijs voor het volgende 15-minuten interval van uw Tibber-abonnement",
"usage_tips": "Gebruik dit om u voor te bereiden op aanstaande prijswijzigingen of om apparaten te plannen om tijdens goedkopere intervallen te draaien"
},
"previous_interval_price": {
"description": "De vorige interval elektriciteitsprijs per kWh",
"long_description": "Toont de prijs voor het vorige 15-minuten interval van je Tibber-abonnement",
"long_description": "Toont de prijs voor het vorige 15-minuten interval van uw Tibber-abonnement",
"usage_tips": "Gebruik dit om eerdere prijswijzigingen te bekijken of prijsgeschiedenis bij te houden"
},
"current_hour_average_price": {
@ -49,33 +36,33 @@
},
"lowest_price_today": {
"description": "De laagste elektriciteitsprijs voor vandaag per kWh",
"long_description": "Toont de laagste prijs per kWh voor de huidige dag van je Tibber-abonnement",
"long_description": "Toont de laagste prijs per kWh voor de huidige dag van uw Tibber-abonnement",
"usage_tips": "Gebruik dit om huidige prijzen te vergelijken met de goedkoopste tijd van de dag"
},
"highest_price_today": {
"description": "De hoogste elektriciteitsprijs voor vandaag per kWh",
"long_description": "Toont de hoogste prijs per kWh voor de huidige dag van je Tibber-abonnement",
"usage_tips": "Gebruik dit om te voorkomen dat je apparaten draait tijdens piekprijstijden"
"long_description": "Toont de hoogste prijs per kWh voor de huidige dag van uw Tibber-abonnement",
"usage_tips": "Gebruik dit om te voorkomen dat u apparaten draait tijdens piekprijstijden"
},
"average_price_today": {
"description": "Typische elektriciteitsprijs voor vandaag per kWh (configureerbare weergave)",
"long_description": "Toont de prijs per kWh voor de huidige dag van je Tibber-abonnement. **Standaard toont de status de mediaan** (resistent tegen extreme prijspieken, toont typisch prijsniveau). Je kunt dit wijzigen in de integratie-instellingen om het rekenkundig gemiddelde te tonen. De alternatieve waarde is beschikbaar als attribuut.",
"usage_tips": "Gebruik dit als basislijn voor het vergelijken van huidige prijzen. Voor berekeningen gebruik: {{ state_attr('sensor.average_price_today', 'price_mean') }}"
"description": "De gemiddelde elektriciteitsprijs voor vandaag per kWh",
"long_description": "Toont de gemiddelde prijs per kWh voor de huidige dag van uw Tibber-abonnement",
"usage_tips": "Gebruik dit als basislijn voor het vergelijken van huidige prijzen"
},
"lowest_price_tomorrow": {
"description": "De laagste elektriciteitsprijs voor morgen per kWh",
"long_description": "Toont de laagste prijs per kWh voor morgen van je Tibber-abonnement. Deze sensor wordt niet beschikbaar totdat de gegevens van morgen door Tibber worden gepubliceerd (meestal rond 13:00-14:00 CET).",
"long_description": "Toont de laagste prijs per kWh voor morgen van uw Tibber-abonnement. Deze sensor wordt niet beschikbaar totdat de gegevens van morgen door Tibber worden gepubliceerd (meestal rond 13:00-14:00 CET).",
"usage_tips": "Gebruik dit om energie-intensieve activiteiten te plannen voor de goedkoopste tijd van morgen. Perfect voor vooraf plannen van verwarming, EV-laden of apparaten."
},
"highest_price_tomorrow": {
"description": "De hoogste elektriciteitsprijs voor morgen per kWh",
"long_description": "Toont de hoogste prijs per kWh voor morgen van je Tibber-abonnement. Deze sensor wordt niet beschikbaar totdat de gegevens van morgen door Tibber worden gepubliceerd (meestal rond 13:00-14:00 CET).",
"usage_tips": "Gebruik dit om te voorkomen dat je apparaten draait tijdens de piekprijstijden van morgen. Handig voor het plannen rond dure perioden."
"long_description": "Toont de hoogste prijs per kWh voor morgen van uw Tibber-abonnement. Deze sensor wordt niet beschikbaar totdat de gegevens van morgen door Tibber worden gepubliceerd (meestal rond 13:00-14:00 CET).",
"usage_tips": "Gebruik dit om te voorkomen dat u apparaten draait tijdens de piekprijstijden van morgen. Handig voor het plannen rond dure perioden."
},
"average_price_tomorrow": {
"description": "Typische elektriciteitsprijs voor morgen per kWh (configureerbare weergave)",
"long_description": "Toont de prijs per kWh voor morgen van je Tibber-abonnement. **Standaard toont de status de mediaan** (resistent tegen extreme prijspieken). Je kunt dit wijzigen in de integratie-instellingen om het rekenkundig gemiddelde te tonen. De alternatieve waarde is beschikbaar als attribuut. Deze sensor wordt niet beschikbaar totdat de gegevens van morgen door Tibber worden gepubliceerd (meestal rond 13:00-14:00 CET).",
"usage_tips": "Gebruik dit als basislijn voor het vergelijken van prijzen van morgen en het plannen van verbruik. Vergelijk met de mediaan van vandaag om te zien of morgen over het algemeen duurder of goedkoper wordt."
"description": "De gemiddelde elektriciteitsprijs voor morgen per kWh",
"long_description": "Toont de gemiddelde prijs per kWh voor morgen van uw Tibber-abonnement. Deze sensor wordt niet beschikbaar totdat de gegevens van morgen door Tibber worden gepubliceerd (meestal rond 13:00-14:00 CET).",
"usage_tips": "Gebruik dit als basislijn voor het vergelijken van prijzen van morgen en het plannen van verbruik. Vergelijk met het gemiddelde van vandaag om te zien of morgen over het algemeen duurder of goedkoper wordt."
},
"yesterday_price_level": {
"description": "Geaggregeerd prijsniveau voor gisteren",
@ -94,48 +81,48 @@
},
"yesterday_price_rating": {
"description": "Geaggregeerde prijsbeoordeling voor gisteren",
"long_description": "Toont de geaggregeerde prijsbeoordeling (laag/normaal/hoog) voor alle intervallen van gisteren, gebaseerd op jouw geconfigureerde drempelwaarden. Gebruikt dezelfde logica als de uursensoren om de totale beoordeling voor de hele dag te bepalen.",
"usage_tips": "Gebruik dit om de prijssituatie van gisteren te begrijpen ten opzichte van jouw persoonlijke drempelwaarden. Vergelijk met vandaag voor trendanalyse."
"long_description": "Toont de geaggregeerde prijsbeoordeling (laag/normaal/hoog) voor alle intervallen van gisteren, gebaseerd op uw geconfigureerde drempelwaarden. Gebruikt dezelfde logica als de uursensoren om de totale beoordeling voor de hele dag te bepalen.",
"usage_tips": "Gebruik dit om de prijssituatie van gisteren te begrijpen ten opzichte van uw persoonlijke drempelwaarden. Vergelijk met vandaag voor trendanalyse."
},
"today_price_rating": {
"description": "Geaggregeerde prijsbeoordeling voor vandaag",
"long_description": "Toont de geaggregeerde prijsbeoordeling (laag/normaal/hoog) voor alle intervallen van vandaag, gebaseerd op jouw geconfigureerde drempelwaarden. Gebruikt dezelfde logica als de uursensoren om de totale beoordeling voor de hele dag te bepalen.",
"usage_tips": "Gebruik dit om snel de prijssituatie van vandaag te beoordelen ten opzichte van jouw persoonlijke drempelwaarden. Helpt bij het nemen van verbruiksbeslissingen voor de huidige dag."
"long_description": "Toont de geaggregeerde prijsbeoordeling (laag/normaal/hoog) voor alle intervallen van vandaag, gebaseerd op uw geconfigureerde drempelwaarden. Gebruikt dezelfde logica als de uursensoren om de totale beoordeling voor de hele dag te bepalen.",
"usage_tips": "Gebruik dit om snel de prijssituatie van vandaag te beoordelen ten opzichte van uw persoonlijke drempelwaarden. Helpt bij het nemen van verbruiksbeslissingen voor de huidige dag."
},
"tomorrow_price_rating": {
"description": "Geaggregeerde prijsbeoordeling voor morgen",
"long_description": "Toont de geaggregeerde prijsbeoordeling (laag/normaal/hoog) voor alle intervallen van morgen, gebaseerd op jouw geconfigureerde drempelwaarden. Gebruikt dezelfde logica als de uursensoren om de totale beoordeling voor de hele dag te bepalen. Deze sensor wordt niet beschikbaar totdat de gegevens van morgen door Tibber worden gepubliceerd (meestal rond 13:00-14:00 CET).",
"usage_tips": "Gebruik dit om het energieverbruik van morgen te plannen op basis van jouw persoonlijke prijsdrempelwaarden. Vergelijk met vandaag om te beslissen of je verbruik naar morgen moet verschuiven of vandaag energie moet gebruiken."
"long_description": "Toont de geaggregeerde prijsbeoordeling (laag/normaal/hoog) voor alle intervallen van morgen, gebaseerd op uw geconfigureerde drempelwaarden. Gebruikt dezelfde logica als de uursensoren om de totale beoordeling voor de hele dag te bepalen. Deze sensor wordt niet beschikbaar totdat de gegevens van morgen door Tibber worden gepubliceerd (meestal rond 13:00-14:00 CET).",
"usage_tips": "Gebruik dit om het energieverbruik van morgen te plannen op basis van uw persoonlijke prijsdrempelwaarden. Vergelijk met vandaag om te beslissen of u verbruik naar morgen moet verschuiven of vandaag energie moet gebruiken."
},
"trailing_price_average": {
"description": "Typische elektriciteitsprijs voor de afgelopen 24 uur per kWh (configureerbare weergave)",
"long_description": "Toont de prijs per kWh berekend uit de afgelopen 24 uur. **Standaard toont de status de mediaan** (resistent tegen extreme prijspieken, toont typisch prijsniveau). Je kunt dit wijzigen in de integratie-instellingen om het rekenkundig gemiddelde te tonen. De alternatieve waarde is beschikbaar als attribuut. Wordt elke 15 minuten bijgewerkt.",
"usage_tips": "Gebruik de statuswaarde om het typische huidige prijsniveau te zien. Voor kostenberekeningen gebruik: {{ state_attr('sensor.trailing_price_average', 'price_mean') }}"
"description": "De gemiddelde elektriciteitsprijs voor de afgelopen 24 uur per kWh",
"long_description": "Toont de gemiddelde prijs per kWh berekend uit de afgelopen 24 uur (voortschrijdend gemiddelde) van uw Tibber-abonnement. Dit biedt een voortschrijdend gemiddelde dat elke 15 minuten wordt bijgewerkt op basis van historische gegevens.",
"usage_tips": "Gebruik dit om huidige prijzen te vergelijken met recente trends. Een huidige prijs die aanzienlijk boven dit gemiddelde ligt, kan aangeven dat het een goed moment is om het verbruik te verminderen."
},
"leading_price_average": {
"description": "Typische elektriciteitsprijs voor de komende 24 uur per kWh (configureerbare weergave)",
"long_description": "Toont de prijs per kWh berekend uit de komende 24 uur. **Standaard toont de status de mediaan** (resistent tegen extreme prijspieken, toont verwacht prijsniveau). Je kunt dit wijzigen in de integratie-instellingen om het rekenkundig gemiddelde te tonen. De alternatieve waarde is beschikbaar als attribuut.",
"usage_tips": "Gebruik de statuswaarde om het typische toekomstige prijsniveau te zien. Voor kostenberekeningen gebruik: {{ state_attr('sensor.leading_price_average', 'price_mean') }}"
"description": "De gemiddelde elektriciteitsprijs voor de komende 24 uur per kWh",
"long_description": "Toont de gemiddelde prijs per kWh berekend uit de komende 24 uur (vooruitlopend gemiddelde) van uw Tibber-abonnement. Dit biedt een vooruitkijkend gemiddelde op basis van beschikbare prognosegegevens.",
"usage_tips": "Gebruik dit om energieverbruik te plannen. Als de huidige prijs onder het vooruitlopende gemiddelde ligt, kan het een goed moment zijn om energie-intensieve apparaten te laten draaien."
},
"trailing_price_min": {
"description": "De minimale elektriciteitsprijs voor de afgelopen 24 uur per kWh",
"long_description": "Toont de minimumprijs per kWh van de afgelopen 24 uur (voortschrijdend minimum) van je Tibber-abonnement. Dit geeft de laagste prijs die in de afgelopen 24 uur is gezien.",
"usage_tips": "Gebruik dit om de beste prijsmogelijkheid te zien die je in de afgelopen 24 uur had en vergelijk deze met huidige prijzen."
"long_description": "Toont de minimumprijs per kWh van de afgelopen 24 uur (voortschrijdend minimum) van uw Tibber-abonnement. Dit geeft de laagste prijs die in de afgelopen 24 uur is gezien.",
"usage_tips": "Gebruik dit om de beste prijsmogelijkheid te zien die u in de afgelopen 24 uur had en vergelijk deze met huidige prijzen."
},
"trailing_price_max": {
"description": "De maximale elektriciteitsprijs voor de afgelopen 24 uur per kWh",
"long_description": "Toont de maximumprijs per kWh van de afgelopen 24 uur (voortschrijdend maximum) van je Tibber-abonnement. Dit geeft de hoogste prijs die in de afgelopen 24 uur is gezien.",
"long_description": "Toont de maximumprijs per kWh van de afgelopen 24 uur (voortschrijdend maximum) van uw Tibber-abonnement. Dit geeft de hoogste prijs die in de afgelopen 24 uur is gezien.",
"usage_tips": "Gebruik dit om de piekprijs in de afgelopen 24 uur te zien en prijsvolatiliteit te beoordelen."
},
"leading_price_min": {
"description": "De minimale elektriciteitsprijs voor de komende 24 uur per kWh",
"long_description": "Toont de minimumprijs per kWh van de komende 24 uur (vooruitlopend minimum) van je Tibber-abonnement. Dit geeft de laagste prijs die wordt verwacht in de komende 24 uur op basis van prognosegegevens.",
"long_description": "Toont de minimumprijs per kWh van de komende 24 uur (vooruitlopend minimum) van uw Tibber-abonnement. Dit geeft de laagste prijs die wordt verwacht in de komende 24 uur op basis van prognosegegevens.",
"usage_tips": "Gebruik dit om de beste prijsmogelijkheid te identificeren die eraan komt en plan energie-intensieve taken dienovereenkomstig."
},
"leading_price_max": {
"description": "De maximale elektriciteitsprijs voor de komende 24 uur per kWh",
"long_description": "Toont de maximumprijs per kWh van de komende 24 uur (vooruitlopend maximum) van je Tibber-abonnement. Dit geeft de hoogste prijs die wordt verwacht in de komende 24 uur op basis van prognosegegevens.",
"usage_tips": "Gebruik dit om te voorkomen dat je apparaten draait tijdens aanstaande piekprijsperioden."
"long_description": "Toont de maximumprijs per kWh van de komende 24 uur (vooruitlopend maximum) van uw Tibber-abonnement. Dit geeft de hoogste prijs die wordt verwacht in de komende 24 uur op basis van prognosegegevens.",
"usage_tips": "Gebruik dit om te voorkomen dat u apparaten draait tijdens aanstaande piekprijsperioden."
},
"current_interval_price_level": {
"description": "De huidige prijsniveauclassificatie",
@ -155,7 +142,7 @@
"current_hour_price_level": {
"description": "Geaggregeerd prijsniveau voor huidig voortschrijdend uur (5 intervallen)",
"long_description": "Toont het mediane prijsniveau over 5 intervallen (2 ervoor, huidig, 2 erna) dat ongeveer 75 minuten beslaat. Biedt een stabielere prijsniveauindicator die kortetermijnschommelingen afvlakt.",
"usage_tips": "Gebruik voor planningsbeslissingen op middellange termijn waarbij je niet wilt reageren op korte prijspieken of -dalingen."
"usage_tips": "Gebruik voor planningsbeslissingen op middellange termijn waarbij u niet wilt reageren op korte prijspieken of -dalingen."
},
"next_hour_price_level": {
"description": "Geaggregeerd prijsniveau voor volgend voortschrijdend uur (5 intervallen vooruit)",
@ -185,22 +172,22 @@
"next_hour_price_rating": {
"description": "Geaggregeerde prijsbeoordeling voor volgend voortschrijdend uur (5 intervallen vooruit)",
"long_description": "Toont de gemiddelde beoordeling voor 5 intervallen gecentreerd één uur vooruit. Helpt te begrijpen of het volgende uur over het algemeen boven of onder gemiddelde prijzen zal liggen.",
"usage_tips": "Gebruik om te beslissen of je een uur moet wachten voordat je activiteiten met hoog verbruik start."
"usage_tips": "Gebruik om te beslissen of u een uur moet wachten voordat u activiteiten met hoog verbruik start."
},
"next_avg_1h": {
"description": "Gemiddelde prijs voor het volgende 1 uur (alleen vooruit vanaf volgend interval)",
"long_description": "Vooruitkijkend gemiddelde: Toont gemiddelde van volgende 4 intervallen (1 uur) vanaf het VOLGENDE 15-minuten interval (niet inclusief huidig). Verschilt van current_hour_average_price die vorige intervallen omvat. Gebruik voor absolute prijsdrempelplanning.",
"usage_tips": "Absolute prijsdrempel: Start apparaten alleen wanneer het gemiddelde onder je maximaal acceptabele prijs blijft (bijv. onder 0,25 EUR/kWh). Combineer met trendsensor voor optimale timing. Let op: Dit is GEEN vervanging voor uurprijzen - gebruik current_hour_average_price daarvoor."
"usage_tips": "Absolute prijsdrempel: Start apparaten alleen wanneer het gemiddelde onder uw maximaal acceptabele prijs blijft (bijv. onder 0,25 EUR/kWh). Combineer met trendsensor voor optimale timing. Let op: Dit is GEEN vervanging voor uurprijzen - gebruik current_hour_average_price daarvoor."
},
"next_avg_2h": {
"description": "Gemiddelde prijs voor de volgende 2 uur",
"long_description": "Toont de gemiddelde prijs voor de volgende 8 intervallen (2 uur) vanaf het volgende 15-minuten interval.",
"usage_tips": "Absolute prijsdrempel: Stel een maximaal acceptabele gemiddelde prijs in voor standaard apparaten zoals wasmachines. Zorgt ervoor dat je nooit meer betaalt dan je limiet."
"usage_tips": "Absolute prijsdrempel: Stel een maximaal acceptabele gemiddelde prijs in voor standaard apparaten zoals wasmachines. Zorgt ervoor dat u nooit meer betaalt dan uw limiet."
},
"next_avg_3h": {
"description": "Gemiddelde prijs voor de volgende 3 uur",
"long_description": "Toont de gemiddelde prijs voor de volgende 12 intervallen (3 uur) vanaf het volgende 15-minuten interval.",
"usage_tips": "Absolute prijsdrempel: Voor EU Eco-programma's (vaatwassers, 3-4u looptijd). Start alleen wanneer 3u gemiddelde onder je prijslimiet is. Gebruik met trendsensor om beste moment binnen acceptabel prijsbereik te vinden."
"usage_tips": "Absolute prijsdrempel: Voor EU Eco-programma's (vaatwassers, 3-4u looptijd). Start alleen wanneer 3u gemiddelde onder uw prijslimiet is. Gebruik met trendsensor om beste moment binnen acceptabel prijsbereik te vinden."
},
"next_avg_4h": {
"description": "Gemiddelde prijs voor de volgende 4 uur",
@ -215,32 +202,32 @@
"next_avg_6h": {
"description": "Gemiddelde prijs voor de volgende 6 uur",
"long_description": "Toont de gemiddelde prijs voor de volgende 24 intervallen (6 uur) vanaf het volgende 15-minuten interval.",
"usage_tips": "Absolute prijsdrempel: Avondplanning met prijslimieten. Plan taken alleen als 6u gemiddelde onder je maximaal acceptabele kosten blijft."
"usage_tips": "Absolute prijsdrempel: Avondplanning met prijslimieten. Plan taken alleen als 6u gemiddelde onder uw maximaal acceptabele kosten blijft."
},
"next_avg_8h": {
"description": "Gemiddelde prijs voor de volgende 8 uur",
"long_description": "Toont de gemiddelde prijs voor de volgende 32 intervallen (8 uur) vanaf het volgende 15-minuten interval.",
"usage_tips": "Absolute prijsdrempel: Nachtelijke bedieningsbeslissingen. Stel harde prijslimieten in voor nachtelijke belastingen (batterij opladen, thermische opslag). Overschrijd nooit je budget."
"usage_tips": "Absolute prijsdrempel: Nachtelijke bedieningsbeslissingen. Stel harde prijslimieten in voor nachtelijke belastingen (batterij opladen, thermische opslag). Overschrijd nooit uw budget."
},
"next_avg_12h": {
"description": "Gemiddelde prijs voor de volgende 12 uur",
"long_description": "Toont de gemiddelde prijs voor de volgende 48 intervallen (12 uur) vanaf het volgende 15-minuten interval.",
"usage_tips": "Absolute prijsdrempel: Strategische beslissingen met prijslimieten. Ga alleen door als 12u gemiddelde onder je maximaal acceptabele prijs is. Goed voor uitgestelde grote belastingen."
"usage_tips": "Absolute prijsdrempel: Strategische beslissingen met prijslimieten. Ga alleen door als 12u gemiddelde onder uw maximaal acceptabele prijs is. Goed voor uitgestelde grote belastingen."
},
"price_trend_1h": {
"description": "Prijstrend voor het volgende uur",
"long_description": "Vergelijkt huidige intervalprijs met gemiddelde van volgend 1 uur (4 intervallen). Stijgend als toekomst >5% hoger is, dalend als >5% lager, anders stabiel.",
"usage_tips": "Relatieve optimalisatie: 'dalend' = wacht, prijzen dalen. 'stijgend' = handel nu of je betaalt meer. 'stabiel' = prijs maakt nu niet veel uit. Werkt onafhankelijk van absoluut prijsniveau."
"usage_tips": "Relatieve optimalisatie: 'dalend' = wacht, prijzen dalen. 'stijgend' = handel nu of u betaalt meer. 'stabiel' = prijs maakt nu niet veel uit. Werkt onafhankelijk van absoluut prijsniveau."
},
"price_trend_2h": {
"description": "Prijstrend voor de volgende 2 uur",
"long_description": "Vergelijkt huidige intervalprijs met gemiddelde van volgende 2 uur (8 intervallen). Stijgend als toekomst >5% hoger is, dalend als >5% lager, anders stabiel.",
"usage_tips": "Relatieve optimalisatie: Ideaal voor apparaten. 'dalend' betekent betere prijzen komen over 2u - stel uit indien mogelijk. Vindt beste timing binnen je beschikbare venster, ongeacht seizoen."
"usage_tips": "Relatieve optimalisatie: Ideaal voor apparaten. 'dalend' betekent betere prijzen komen over 2u - stel uit indien mogelijk. Vindt beste timing binnen uw beschikbare venster, ongeacht seizoen."
},
"price_trend_3h": {
"description": "Prijstrend voor de volgende 3 uur",
"long_description": "Vergelijkt huidige intervalprijs met gemiddelde van volgende 3 uur (12 intervallen). Stijgend als toekomst >5% hoger is, dalend als >5% lager, anders stabiel.",
"usage_tips": "Relatieve optimalisatie: Voor Eco-programma's. 'dalend' betekent prijzen dalen >5% - het wachten waard. Werkt in elk seizoen. Combineer met avg-sensor voor prijslimiet: alleen wanneer avg < je limiet EN trend niet 'dalend'."
"usage_tips": "Relatieve optimalisatie: Voor Eco-programma's. 'dalend' betekent prijzen dalen >5% - het wachten waard. Werkt in elk seizoen. Combineer met avg-sensor voor prijslimiet: alleen wanneer avg < uw limiet EN trend niet 'dalend'."
},
"price_trend_4h": {
"description": "Prijstrend voor de volgende 4 uur",
@ -250,12 +237,12 @@
"price_trend_5h": {
"description": "Prijstrend voor de volgende 5 uur",
"long_description": "Vergelijkt huidige intervalprijs met gemiddelde van volgende 5 uur (20 intervallen). Stijgend als toekomst >5% hoger is, dalend als >5% lager, anders stabiel.",
"usage_tips": "Relatieve optimalisatie: Uitgebreide operaties. Past zich aan de markt aan - vindt beste relatieve timing in elke prijsomgeving. 'stabiel/stijgend' = goed moment om te starten binnen je planningsvenster."
"usage_tips": "Relatieve optimalisatie: Uitgebreide operaties. Past zich aan de markt aan - vindt beste relatieve timing in elke prijsomgeving. 'stabiel/stijgend' = goed moment om te starten binnen uw planningsvenster."
},
"price_trend_6h": {
"description": "Prijstrend voor de volgende 6 uur",
"long_description": "Vergelijkt huidige intervalprijs met gemiddelde van volgende 6 uur (24 intervallen). Stijgend als toekomst >5% hoger is, dalend als >5% lager, anders stabiel.",
"usage_tips": "Relatieve optimalisatie: Avandbeslissingen. 'dalend' = prijzen verbeteren aanzienlijk als je wacht. Geen vaste drempels nodig - past automatisch aan winter/zomer prijsniveaus."
"usage_tips": "Relatieve optimalisatie: Avandbeslissingen. 'dalend' = prijzen verbeteren aanzienlijk als u wacht. Geen vaste drempels nodig - past automatisch aan winter/zomer prijsniveaus."
},
"price_trend_8h": {
"description": "Prijstrend voor de volgende 8 uur",
@ -289,77 +276,67 @@
},
"data_timestamp": {
"description": "Tijdstempel van het laatst beschikbare prijsgegevensinterval",
"long_description": "Toont het tijdstempel van het laatst beschikbare prijsgegevensinterval van je Tibber-abonnement"
"long_description": "Toont het tijdstempel van het laatst beschikbare prijsgegevensinterval van uw Tibber-abonnement"
},
"today_volatility": {
"description": "Hoeveel de stroomprijzen vandaag schommelen",
"long_description": "Geeft aan of de prijzen vandaag stabiel blijven of grote schommelingen hebben. Lage volatiliteit betekent vrij constante prijzen timing maakt weinig uit. Hoge volatiliteit betekent duidelijke prijsverschillen gedurende de dag goede kans om verbruik naar goedkopere periodes te verschuiven. `price_coefficient_variation_%` toont het percentage, `price_spread` de absolute prijsspanne.",
"usage_tips": "Gebruik dit om te beslissen of optimaliseren de moeite waard is. Bij lage volatiliteit kun je apparaten op elk moment laten draaien. Bij hoge volatiliteit bespaar je merkbaar door Best Price-periodes te volgen."
"description": "Prijsvolatiliteitsclassificatie voor vandaag",
"long_description": "Toont hoeveel elektriciteitsprijzen variëren gedurende vandaag op basis van de spreiding (verschil tussen hoogste en laagste prijs). Classificatie: LOW = spreiding < 5ct, MODERATE = 5-15ct, HIGH = 15-30ct, VERY HIGH = >30ct.",
"usage_tips": "Gebruik dit om te bepalen of prijsgebaseerde optimalisatie de moeite waard is. Bijvoorbeeld, met een balkonbatterij met 15% efficiëntieverlies is optimalisatie alleen zinvol wanneer volatiliteit ten minste MODERATE is. Maak automatiseringen die volatiliteit controleren voordat u laad-/ontlaadcycli plant."
},
"tomorrow_volatility": {
"description": "Hoeveel de stroomprijzen morgen zullen schommelen",
"long_description": "Geeft aan of de prijzen morgen stabiel blijven of grote schommelingen hebben. Beschikbaar zodra de gegevens voor morgen zijn gepubliceerd (meestal 13:0014:00 CET). Lage volatiliteit betekent vrij constante prijzen timing is niet kritisch. Hoge volatiliteit betekent duidelijke prijsverschillen gedurende de dag goede kans om energie-intensieve taken te plannen. `price_coefficient_variation_%` toont het percentage, `price_spread` de absolute prijsspanne.",
"usage_tips": "Gebruik dit om het verbruik van morgen te plannen. Hoge volatiliteit? Plan flexibele lasten in Best Price-periodes. Lage volatiliteit? Laat apparaten draaien wanneer het jou uitkomt."
"description": "Prijsvolatiliteitsclassificatie voor morgen",
"long_description": "Toont hoeveel elektriciteitsprijzen zullen variëren gedurende morgen op basis van de spreiding (verschil tussen hoogste en laagste prijs). Wordt onbeschikbaar totdat de gegevens van morgen zijn gepubliceerd (meestal 13:00-14:00 CET).",
"usage_tips": "Gebruik dit voor vooruitplanning van het energieverbruik van morgen. Als morgen HIGH of VERY HIGH volatiliteit heeft, is het de moeite waard om de timing van energieverbruik te optimaliseren. Bij LOW kunt u apparaten op elk moment gebruiken zonder significante kostenverschillen."
},
"next_24h_volatility": {
"description": "Hoeveel de prijzen de komende 24 uur zullen schommelen",
"long_description": "Geeft de prijsvolatiliteit aan voor een rollend 24-uursvenster vanaf nu (wordt elke 15 minuten bijgewerkt). Lage volatiliteit betekent vrij constante prijzen. Hoge volatiliteit betekent merkbare prijsschommelingen en dus optimalisatiemogelijkheden. In tegenstelling tot vandaag/morgen-sensoren overschrijdt deze daggrenzen en geeft een doorlopende vooruitblik. `price_coefficient_variation_%` toont het percentage, `price_spread` de absolute prijsspanne.",
"usage_tips": "Het beste voor beslissingen in real-time. Gebruik bij het plannen van batterijladen of andere flexibele lasten die over middernacht kunnen lopen. Biedt een consistent 24-uurs beeld, los van de kalenderdag."
"description": "Prijsvolatiliteitsclassificatie voor de rollende volgende 24 uur",
"long_description": "Toont hoeveel elektriciteitsprijzen variëren in de volgende 24 uur vanaf nu (rollend venster). Dit overschrijdt daggrenzen en wordt elke 15 minuten bijgewerkt, wat een vooruitkijkende volatiliteitsbeoordeling biedt onafhankelijk van kalenderdagen.",
"usage_tips": "Beste sensor voor realtime optimalisatiebeslissingen. In tegenstelling tot vandaag/morgen-sensoren die om middernacht wisselen, biedt deze een continue 24-uurs volatiliteitsbeoordeling. Gebruik voor batterijlaadstrategieën die over daggrenzen heen gaan."
},
"today_tomorrow_volatility": {
"description": "Gecombineerde prijsvolatiliteit voor vandaag en morgen",
"long_description": "Geeft de totale volatiliteit weer wanneer vandaag en morgen samen worden bekeken (zodra morgengegevens beschikbaar zijn). Toont of er duidelijke prijsverschillen over de daggrens heen zijn. Valt terug naar alleen vandaag als morgengegevens ontbreken. Handig voor meerdaagse optimalisatie. `price_coefficient_variation_%` toont het percentage, `price_spread` de absolute prijsspanne.",
"usage_tips": "Gebruik voor taken die meerdere dagen beslaan. Kijk of de prijsverschillen groot genoeg zijn om plannen op te baseren. De afzonderlijke dag-sensoren tonen per-dag bijdragen als je meer detail wilt."
"description": "Gecombineerde prijsvolatiliteitsclassificatie voor vandaag en morgen",
"long_description": "Toont volatiliteit over zowel vandaag als morgen gecombineerd (wanneer de gegevens van morgen beschikbaar zijn). Biedt een uitgebreid beeld van prijsvariatie over maximaal 48 uur. Valt terug op alleen vandaag wanneer de gegevens van morgen nog niet beschikbaar zijn.",
"usage_tips": "Gebruik dit voor meerdaagse planning en om te begrijpen of prijskansen bestaan over de daggrens heen. De 'today_volatility' en 'tomorrow_volatility' breakdown-attributen tonen individuele dagbijdragen. Nuttig voor het plannen van laadsessies die middernacht kunnen overschrijden."
},
"data_lifecycle_status": {
"description": "Huidige status van prijsgegevenslevenscyclus en caching",
"long_description": "Toont of de integratie gebruikmaakt van gecachte gegevens of verse gegevens van de API. Toont huidige levenscyclusstatus: 'cached' (gebruikt opgeslagen gegevens), 'fresh' (net opgehaald van API), 'refreshing' (momenteel aan het ophalen), 'searching_tomorrow' (actief aan het zoeken naar morgengegevens na 13:00), 'turnover_pending' (binnen 15 minuten voor middernacht, 23:45-00:00), of 'error' (ophalen mislukt). Bevat uitgebreide attributen zoals cache-leeftijd, volgende API-poll-tijd, gegevensvolledigheid en API-aanroepstatistieken.",
"usage_tips": "Gebruik deze diagnostische sensor om gegevensfrisheid en API-aanroeppatronen te begrijpen. Controleer het 'cache_age'-attribuut om te zien hoe oud de huidige gegevens zijn. Monitor 'next_api_poll' om te weten wanneer de volgende update is gepland. Gebruik 'data_completeness' om te zien of gisteren/vandaag/morgen gegevens beschikbaar zijn. De 'api_calls_today'-teller helpt API-gebruik bij te houden. Perfect voor probleemoplossing of begrip van integratiegedrag."
"price_forecast": {
"description": "Prognose van aanstaande elektriciteitsprijzen",
"long_description": "Toont aanstaande elektriciteitsprijzen voor toekomstige intervallen in een formaat dat gemakkelijk te gebruiken is in dashboards",
"usage_tips": "Gebruik de attributen van deze entiteit om aanstaande prijzen weer te geven in grafieken of aangepaste kaarten. Toegang tot 'intervals' voor alle toekomstige intervallen of 'hours' voor uuroverzichten."
},
"best_price_end_time": {
"description": "Totale lengte van huidige of volgende voordelige periode (state in uren, attribuut in minuten)",
"long_description": "Toont hoe lang de voordelige periode duurt. State gebruikt uren (float) voor een leesbare UI; attribuut `period_duration_minutes` behoudt afgeronde minuten voor automatiseringen. Actief → duur van de huidige periode, anders de volgende.",
"usage_tips": "UI kan 1,5 u tonen terwijl `period_duration_minutes` = 90 voor automatiseringen blijft."
},
"best_price_period_duration": {
"description": "Lengte van huidige/volgende goedkope periode",
"long_description": "Totale duur van huidige of volgende goedkope periode. De state wordt weergegeven in uren (bijv. 1,5 u) voor gemakkelijk aflezen in de UI, terwijl het attribuut `period_duration_minutes` dezelfde waarde in minuten levert (bijv. 90) voor automatiseringen. Deze waarde vertegenwoordigt de **volledige geplande duur** van de periode en is constant gedurende de gehele periode, zelfs als de resterende tijd (remaining_minutes) afneemt.",
"usage_tips": "Combineer met remaining_minutes om te berekenen wanneer langlopende apparaten moeten worden gestopt: Periode is `period_duration_minutes - remaining_minutes` minuten geleden gestart. Dit attribuut ondersteunt energie-optimalisatiestrategieën door te helpen bij het plannen van hoog-verbruiksactiviteiten binnen goedkope periodes."
"description": "Wanneer de huidige of volgende goedkope periode eindigt",
"long_description": "Toont het eindtijdstempel van de huidige goedkope periode wanneer actief, of het einde van de volgende periode wanneer geen periode actief is. Toont altijd een nuttige tijdreferentie voor planning. Geeft alleen 'Onbekend' terug wanneer geen periodes zijn geconfigureerd.",
"usage_tips": "Gebruik dit om een aftelling weer te geven zoals 'Goedkope periode eindigt over 2 uur' (wanneer actief) of 'Volgende goedkope periode eindigt om 14:00' (wanneer inactief). Home Assistant toont automatisch relatieve tijd voor tijdstempelsensoren."
},
"best_price_remaining_minutes": {
"description": "Resterende tijd in huidige goedkope periode",
"long_description": "Toont hoeveel tijd er nog overblijft in de huidige goedkope periode. De state wordt weergegeven in uren (bijv. 0,75 u) voor gemakkelijk aflezen in dashboards, terwijl het attribuut `remaining_minutes` dezelfde tijd in minuten levert (bijv. 45) voor automatiseringsvoorwaarden. **Afteltimer**: Deze waarde neemt elke minuut af tijdens een actieve periode. Geeft 0 terug wanneer geen goedkope periode actief is. Werkt elke minuut bij.",
"usage_tips": "Voor automatiseringen: Gebruik attribuut `remaining_minutes` zoals 'Als remaining_minutes > 60, start vaatwasser nu (genoeg tijd om te voltooien)' of 'Als remaining_minutes < 15, rond huidige cyclus binnenkort af'. UI toont gebruiksvriendelijke uren (bijv. 1,25 u). Waarde 0 geeft aan dat geen goedkope periode actief is."
"description": "Resterende minuten in huidige goedkope periode (0 wanneer inactief)",
"long_description": "Toont hoeveel minuten er nog over zijn in de huidige goedkope periode. Geeft 0 terug wanneer geen periode actief is. Werkt elke minuut bij. Controleer binary_sensor.best_price_period om te zien of een periode momenteel actief is.",
"usage_tips": "Perfect voor automatiseringen: 'Als remaining_minutes > 0 EN remaining_minutes < 30, start wasmachine nu'. De waarde 0 maakt het gemakkelijk om te controleren of een periode actief is (waarde > 0) of niet (waarde = 0)."
},
"best_price_progress": {
"description": "Voortgang door huidige goedkope periode (0% wanneer inactief)",
"long_description": "Toont voortgang door de huidige goedkope periode als 0-100%. Geeft 0% terug wanneer geen periode actief is. Werkt elke minuut bij. 0% betekent periode net gestart, 100% betekent dat deze bijna eindigt.",
"usage_tips": "Geweldig voor visuele voortgangsbalken. Gebruik in automatiseringen: 'Als progress > 0 EN progress > 75, stuur melding dat goedkope periode bijna eindigt'. Waarde 0 geeft aan dat geen periode actief is."
"long_description": "Toont de voortgang door de huidige goedkope periode als 0-100%. Geeft 0% terug wanneer geen periode actief is. Werkt elke minuut bij. 0% betekent periode net gestart, 100% betekent het eindigt bijna.",
"usage_tips": "Geweldig voor visuele voortgangsbalken. Gebruik in automatiseringen: 'Als progress > 0 EN progress > 75, stuur melding dat goedkope periode bijna eindigt'. Waarde 0 geeft aan dat er geen actieve periode is."
},
"best_price_next_start_time": {
"description": "Totale lengte van huidige of volgende dure periode (state in uren, attribuut in minuten)",
"long_description": "Toont hoe lang de dure periode duurt. State gebruikt uren (float) voor de UI; attribuut `period_duration_minutes` behoudt afgeronde minuten voor automatiseringen. Actief → duur van de huidige periode, anders de volgende.",
"usage_tips": "UI kan 0,75 u tonen terwijl `period_duration_minutes` = 45 voor automatiseringen blijft."
"description": "Wanneer de volgende goedkope periode begint",
"long_description": "Toont wanneer de volgende komende goedkope periode begint. Tijdens een actieve periode toont dit de start van de VOLGENDE periode na de huidige. Geeft alleen 'Onbekend' terug wanneer geen toekomstige periodes zijn geconfigureerd.",
"usage_tips": "Altijd nuttig voor vooruitplanning: 'Volgende goedkope periode begint over 3 uur' (of je nu in een periode zit of niet). Combineer met automatiseringen: 'Wanneer volgende starttijd over 10 minuten is, stuur melding om wasmachine voor te bereiden'."
},
"best_price_next_in_minutes": {
"description": "Resterende tijd in huidige dure periode (state in uren, attribuut in minuten)",
"long_description": "Toont hoeveel tijd er nog over is. State gebruikt uren (float); attribuut `remaining_minutes` behoudt afgeronde minuten voor automatiseringen. Geeft 0 terug wanneer er geen periode actief is. Werkt elke minuut bij.",
"usage_tips": "Gebruik `remaining_minutes` voor drempels (bijv. > 60) terwijl de state in uren goed leesbaar blijft."
"description": "Minuten tot volgende goedkope periode begint (0 bij overgang)",
"long_description": "Toont minuten tot de volgende goedkope periode begint. Tijdens een actieve periode toont dit de tijd tot de periode NA de huidige. Geeft 0 terug tijdens korte overgangsmomenten. Werkt elke minuut bij.",
"usage_tips": "Perfect voor 'wacht tot goedkope periode' automatiseringen: 'Als next_in_minutes > 0 EN next_in_minutes < 15, wacht voordat vaatwasser wordt gestart'. Waarde > 0 geeft altijd aan dat een toekomstige periode is gepland."
},
"peak_price_end_time": {
"description": "Tijd tot volgende dure periode (state in uren, attribuut in minuten)",
"long_description": "Toont hoe lang het duurt tot de volgende dure periode start. State gebruikt uren (float); attribuut `next_in_minutes` behoudt afgeronde minuten voor automatiseringen. Tijdens een actieve periode is dit de tijd tot de periode na de huidige. 0 tijdens korte overgangen. Werkt elke minuut bij.",
"usage_tips": "Gebruik `next_in_minutes` in automatiseringen (bijv. < 10) terwijl de state in uren leesbaar blijft."
},
"peak_price_period_duration": {
"description": "Totale duur van huidige of volgende dure periode in minuten",
"long_description": "Toont de totale duur van de dure periode in minuten. Tijdens een actieve periode toont dit de volledige lengte van de huidige periode. Wanneer geen periode actief is, toont dit de duur van de volgende komende periode. Voorbeeld: '60 minuten' voor een 1-uur periode.",
"usage_tips": "Gebruik om energiebesparende maatregelen te plannen: 'Als duration > 120, verlaag verwarmingstemperatuur agressiever (lange dure periode)'. Helpt bij het inschatten hoeveel energieverbruik moet worden verminderd."
"description": "Wanneer de huidige of volgende dure periode eindigt",
"long_description": "Toont het eindtijdstempel van de huidige dure periode wanneer actief, of het einde van de volgende periode wanneer geen periode actief is. Toont altijd een nuttige tijdreferentie voor planning. Geeft alleen 'Onbekend' terug wanneer geen periodes zijn geconfigureerd.",
"usage_tips": "Gebruik dit om 'Dure periode eindigt over 1 uur' weer te geven (wanneer actief) of 'Volgende dure periode eindigt om 18:00' (wanneer inactief). Combineer met automatiseringen om activiteiten te hervatten na piek."
},
"peak_price_remaining_minutes": {
"description": "Resterende tijd in huidige dure periode",
"long_description": "Toont hoeveel tijd er nog overblijft in de huidige dure periode. De state wordt weergegeven in uren (bijv. 0,75 u) voor gemakkelijk aflezen in dashboards, terwijl het attribuut `remaining_minutes` dezelfde tijd in minuten levert (bijv. 45) voor automatiseringsvoorwaarden. **Afteltimer**: Deze waarde neemt elke minuut af tijdens een actieve periode. Geeft 0 terug wanneer geen dure periode actief is. Werkt elke minuut bij.",
"usage_tips": "Voor automatiseringen: Gebruik attribuut `remaining_minutes` zoals 'Als remaining_minutes > 60, annuleer uitgestelde laadronde' of 'Als remaining_minutes < 15, hervat normaal gebruik binnenkort'. UI toont gebruiksvriendelijke uren (bijv. 1,0 u). Waarde 0 geeft aan dat geen dure periode actief is."
"description": "Resterende minuten in huidige dure periode (0 wanneer inactief)",
"long_description": "Toont hoeveel minuten er nog over zijn in de huidige dure periode. Geeft 0 terug wanneer geen periode actief is. Werkt elke minuut bij. Controleer binary_sensor.peak_price_period om te zien of een periode momenteel actief is.",
"usage_tips": "Gebruik in automatiseringen: 'Als remaining_minutes > 60, annuleer uitgestelde laadronde'. Waarde 0 maakt het gemakkelijk om onderscheid te maken tussen actieve (waarde > 0) en inactieve (waarde = 0) periodes."
},
"peak_price_progress": {
"description": "Voortgang door huidige dure periode (0% wanneer inactief)",
@ -372,9 +349,19 @@
"usage_tips": "Altijd nuttig voor planning: 'Volgende dure periode begint over 2 uur'. Automatisering: 'Wanneer volgende starttijd over 30 minuten is, verlaag verwarmingstemperatuur preventief'."
},
"peak_price_next_in_minutes": {
"description": "Tijd tot volgende dure periode",
"long_description": "Toont hoe lang het duurt tot de volgende dure periode. De state wordt weergegeven in uren (bijv. 0,5 u) voor dashboards, terwijl het attribuut `next_in_minutes` minuten levert (bijv. 30) voor automatiseringsvoorwaarden. Tijdens een actieve periode toont dit de tijd tot de periode NA de huidige. Geeft 0 terug tijdens korte overgangsmomenten. Werkt elke minuut bij.",
"usage_tips": "Voor automatiseringen: Gebruik attribuut `next_in_minutes` zoals 'Als next_in_minutes > 0 EN next_in_minutes < 10, voltooi huidige laadcyclus nu voordat prijzen stijgen'. Waarde > 0 geeft altijd aan dat een toekomstige dure periode is gepland."
"description": "Minuten tot volgende dure periode begint (0 bij overgang)",
"long_description": "Toont minuten tot de volgende dure periode begint. Tijdens een actieve periode toont dit de tijd tot de periode NA de huidige. Geeft 0 terug tijdens korte overgangsmomenten. Werkt elke minuut bij.",
"usage_tips": "Preventieve automatisering: 'Als next_in_minutes > 0 EN next_in_minutes < 10, voltooi huidige laadcyclus nu voordat prijzen stijgen'."
},
"best_price_period_duration": {
"description": "Totale duur van huidige of volgende goedkope periode in minuten",
"long_description": "Toont de totale duur van de goedkope periode in minuten. Tijdens een actieve periode toont dit de volledige lengte van de huidige periode. Wanneer geen periode actief is, toont dit de duur van de volgende komende periode. Voorbeeld: '90 minuten' voor een 1,5-uur periode.",
"usage_tips": "Combineer met remaining_minutes voor taakplanning: 'Als duration = 120 EN remaining_minutes > 90, start wasmachine (genoeg tijd om te voltooien)'. Nuttig om te begrijpen of periodes lang genoeg zijn voor energie-intensieve taken."
},
"peak_price_period_duration": {
"description": "Totale duur van huidige of volgende dure periode in minuten",
"long_description": "Toont de totale duur van de dure periode in minuten. Tijdens een actieve periode toont dit de volledige lengte van de huidige periode. Wanneer geen periode actief is, toont dit de duur van de volgende komende periode. Voorbeeld: '60 minuten' voor een 1-uur periode.",
"usage_tips": "Gebruik om energiebesparende maatregelen te plannen: 'Als duration > 120, verlaag verwarmingstemperatuur agressiever (lange dure periode)'. Helpt bij het inschatten hoeveel energieverbruik moet worden verminderd."
},
"home_type": {
"description": "Type woning (appartement, huis enz.)",
@ -450,11 +437,6 @@
"description": "Data-export voor dashboard-integraties",
"long_description": "Deze sensor roept de get_chartdata-service aan met jouw geconfigureerde YAML-configuratie en stelt het resultaat beschikbaar als entiteitsattributen. De status toont 'ready' wanneer data beschikbaar is, 'error' bij fouten, of 'pending' voor de eerste aanroep. Perfekt voor dashboard-integraties zoals ApexCharts die prijsgegevens uit entiteitsattributen moeten lezen.",
"usage_tips": "Configureer de YAML-parameters in de integratie-opties om overeen te komen met jouw get_chartdata-service-aanroep. De sensor wordt automatisch bijgewerkt wanneer prijsgegevens worden bijgewerkt (typisch na middernacht en wanneer gegevens van morgen binnenkomen). Krijg toegang tot de service-responsgegevens direct vanuit de entiteitsattributen - de structuur komt exact overeen met wat get_chartdata retourneert."
},
"chart_metadata": {
"description": "Lichtgewicht metadata voor diagramconfiguratie",
"long_description": "Biedt essentiële diagramconfiguratiewaarden als sensorattributen. Nuttig voor elke grafiekkaart die Y-as-grenzen nodig heeft. De sensor roept get_chartdata aan in alleen-metadata-modus (geen dataverwerking) en extraheert: yaxis_min, yaxis_max (gesuggereerd Y-asbereik voor optimale schaling). De status weerspiegelt het service-aanroepresultaat: 'ready' bij succes, 'error' bij fouten, 'pending' tijdens initialisatie.",
"usage_tips": "Configureer via configuration.yaml onder tibber_prices.chart_metadata_config (optioneel: day, subunit_currency, resolution). De sensor wordt automatisch bijgewerkt bij prijsgegevenswijzigingen. Krijg toegang tot metadata vanuit attributen: yaxis_min, yaxis_max. Gebruik met config-template-card of elk hulpmiddel dat entiteitsattributen leest - perfect voor dynamische diagramconfiguratie zonder handmatige berekeningen."
}
},
"binary_sensor": {
@ -466,7 +448,7 @@
"peak_price_period": {
"description": "Of het huidige interval tot de duurste van de dag behoort",
"long_description": "Wordt geactiveerd wanneer de huidige prijs in de top 20% van de prijzen van vandaag ligt",
"usage_tips": "Gebruik dit om te voorkomen dat je apparaten met hoog verbruik draait tijdens dure intervallen"
"usage_tips": "Gebruik dit om te voorkomen dat u apparaten met hoog verbruik draait tijdens dure intervallen"
},
"best_price_period": {
"description": "Of het huidige interval tot de goedkoopste van de dag behoort",
@ -487,80 +469,11 @@
"description": "Of realtime verbruiksmonitoring actief is",
"long_description": "Geeft aan of realtime elektriciteitsverbruikmonitoring is ingeschakeld en actief voor je Tibber-woning. Dit vereist compatibele meethardware (bijv. Tibber Pulse) en een actief abonnement.",
"usage_tips": "Gebruik dit om te verifiëren dat realtimeverbruiksgegevens beschikbaar zijn. Schakel meldingen in als dit onverwacht verandert naar 'uit', wat wijst op mogelijke hardware- of verbindingsproblemen."
}
},
"number": {
"best_price_flex_override": {
"description": "Maximaal percentage boven de dagelijkse minimumprijs dat intervallen kunnen hebben en nog steeds als 'beste prijs' kwalificeren. Aanbevolen: 15-20 met versoepeling ingeschakeld (standaard), of 25-35 zonder versoepeling. Maximum: 50 (harde limiet voor betrouwbare periodedetectie).",
"long_description": "Wanneer deze entiteit is ingeschakeld, overschrijft de waarde de 'Flexibiliteit'-instelling uit de opties-dialoog voor beste prijs-periodeberekeningen.",
"usage_tips": "Schakel deze entiteit in om beste prijs-detectie dynamisch aan te passen via automatiseringen, bijv. hogere flexibiliteit voor kritieke lasten of strengere eisen voor flexibele apparaten."
},
"best_price_min_distance_override": {
"description": "Minimale procentuele afstand onder het daggemiddelde. Intervallen moeten zo ver onder het gemiddelde liggen om als 'beste prijs' te kwalificeren. Helpt echte lage prijsperioden te onderscheiden van gemiddelde prijzen.",
"long_description": "Wanneer deze entiteit is ingeschakeld, overschrijft de waarde de 'Minimale afstand'-instelling uit de opties-dialoog voor beste prijs-periodeberekeningen.",
"usage_tips": "Verhoog de waarde voor strengere beste prijs-criteria. Verlaag als te weinig perioden worden gedetecteerd."
},
"best_price_min_period_length_override": {
"description": "Minimale periodelengte in 15-minuten intervallen. Perioden korter dan dit worden niet gerapporteerd. Voorbeeld: 2 = minimaal 30 minuten.",
"long_description": "Wanneer deze entiteit is ingeschakeld, overschrijft de waarde de 'Minimale periodelengte'-instelling uit de opties-dialoog voor beste prijs-periodeberekeningen.",
"usage_tips": "Pas aan op typische apparaatlooptijd: 2 (30 min) voor snelle programma's, 4-8 (1-2 uur) voor normale cycli, 8+ voor lange ECO-programma's."
},
"best_price_min_periods_override": {
"description": "Minimum aantal beste prijs-perioden om dagelijks te vinden. Wanneer versoepeling is ingeschakeld, past het systeem automatisch de criteria aan om dit aantal te bereiken.",
"long_description": "Wanneer deze entiteit is ingeschakeld, overschrijft de waarde de 'Minimum periodes'-instelling uit de opties-dialoog voor beste prijs-periodeberekeningen.",
"usage_tips": "Stel dit in op het aantal tijdkritieke taken dat je dagelijks hebt. Voorbeeld: 2 voor twee wasladingen."
},
"best_price_relaxation_attempts_override": {
"description": "Aantal pogingen om de criteria geleidelijk te versoepelen om het minimum aantal perioden te bereiken. Elke poging verhoogt de flexibiliteit met 3 procent. Bij 0 worden alleen basiscriteria gebruikt.",
"long_description": "Wanneer deze entiteit is ingeschakeld, overschrijft de waarde de 'Versoepeling pogingen'-instelling uit de opties-dialoog voor beste prijs-periodeberekeningen.",
"usage_tips": "Hogere waarden maken periodedetectie adaptiever voor dagen met stabiele prijzen. Stel in op 0 om strikte criteria af te dwingen zonder versoepeling."
},
"best_price_gap_count_override": {
"description": "Maximum aantal duurdere intervallen dat mag worden toegestaan tussen goedkope intervallen terwijl ze nog steeds als één aaneengesloten periode tellen. Bij 0 moeten goedkope intervallen opeenvolgend zijn.",
"long_description": "Wanneer deze entiteit is ingeschakeld, overschrijft de waarde de 'Gap tolerantie'-instelling uit de opties-dialoog voor beste prijs-periodeberekeningen.",
"usage_tips": "Verhoog dit voor apparaten met variabele belasting (bijv. warmtepompen) die korte duurdere intervallen kunnen tolereren. Stel in op 0 voor continu goedkope perioden."
},
"peak_price_flex_override": {
"description": "Maximaal percentage onder de dagelijkse maximumprijs dat intervallen kunnen hebben en nog steeds als 'piekprijs' kwalificeren. Dezelfde aanbevelingen als voor beste prijs-flexibiliteit.",
"long_description": "Wanneer deze entiteit is ingeschakeld, overschrijft de waarde de 'Flexibiliteit'-instelling uit de opties-dialoog voor piekprijs-periodeberekeningen.",
"usage_tips": "Gebruik dit om de piekprijs-drempel tijdens runtime aan te passen voor automatiseringen die verbruik tijdens dure uren vermijden."
},
"peak_price_min_distance_override": {
"description": "Minimale procentuele afstand boven het daggemiddelde. Intervallen moeten zo ver boven het gemiddelde liggen om als 'piekprijs' te kwalificeren.",
"long_description": "Wanneer deze entiteit is ingeschakeld, overschrijft de waarde de 'Minimale afstand'-instelling uit de opties-dialoog voor piekprijs-periodeberekeningen.",
"usage_tips": "Verhoog de waarde om alleen extreme prijspieken te vangen. Verlaag om meer dure tijden mee te nemen."
},
"peak_price_min_period_length_override": {
"description": "Minimale periodelengte in 15-minuten intervallen voor piekprijzen. Kortere prijspieken worden niet als perioden gerapporteerd.",
"long_description": "Wanneer deze entiteit is ingeschakeld, overschrijft de waarde de 'Minimale periodelengte'-instelling uit de opties-dialoog voor piekprijs-periodeberekeningen.",
"usage_tips": "Kortere waarden vangen korte prijspieken. Langere waarden focussen op aanhoudende dure perioden."
},
"peak_price_min_periods_override": {
"description": "Minimum aantal piekprijs-perioden om dagelijks te vinden.",
"long_description": "Wanneer deze entiteit is ingeschakeld, overschrijft de waarde de 'Minimum periodes'-instelling uit de opties-dialoog voor piekprijs-periodeberekeningen.",
"usage_tips": "Stel dit in op basis van hoeveel dure perioden je per dag wilt vangen voor automatiseringen."
},
"peak_price_relaxation_attempts_override": {
"description": "Aantal pogingen om de criteria te versoepelen om het minimum aantal piekprijs-perioden te bereiken.",
"long_description": "Wanneer deze entiteit is ingeschakeld, overschrijft de waarde de 'Versoepeling pogingen'-instelling uit de opties-dialoog voor piekprijs-periodeberekeningen.",
"usage_tips": "Verhoog dit als geen perioden worden gevonden op dagen met stabiele prijzen. Stel in op 0 om strikte criteria af te dwingen."
},
"peak_price_gap_count_override": {
"description": "Maximum aantal goedkopere intervallen dat mag worden toegestaan tussen dure intervallen terwijl ze nog steeds als één piekprijs-periode tellen.",
"long_description": "Wanneer deze entiteit is ingeschakeld, overschrijft de waarde de 'Gap tolerantie'-instelling uit de opties-dialoog voor piekprijs-periodeberekeningen.",
"usage_tips": "Hogere waarden vangen langere dure perioden zelfs met korte prijsdips. Stel in op 0 voor strikt aaneengesloten piekprijzen."
}
},
"switch": {
"best_price_enable_relaxation_override": {
"description": "Indien ingeschakeld, worden criteria automatisch versoepeld om het minimum aantal perioden te bereiken. Indien uitgeschakeld, worden alleen perioden gerapporteerd die aan strikte criteria voldoen (mogelijk nul perioden op dagen met stabiele prijzen).",
"long_description": "Wanneer deze entiteit is ingeschakeld, overschrijft de waarde de 'Minimum aantal bereiken'-instelling uit de opties-dialoog voor beste prijs-periodeberekeningen.",
"usage_tips": "Schakel dit in voor gegarandeerde dagelijkse automatiseringsmogelijkheden. Schakel uit als je alleen echt goedkope perioden wilt, ook als dat betekent dat er op sommige dagen geen perioden zijn."
},
"peak_price_enable_relaxation_override": {
"description": "Indien ingeschakeld, worden criteria automatisch versoepeld om het minimum aantal perioden te bereiken. Indien uitgeschakeld, worden alleen echte prijspieken gerapporteerd.",
"long_description": "Wanneer deze entiteit is ingeschakeld, overschrijft de waarde de 'Minimum aantal bereiken'-instelling uit de opties-dialoog voor piekprijs-periodeberekeningen.",
"usage_tips": "Schakel dit in voor consistente piekprijs-waarschuwingen. Schakel uit om alleen extreme prijspieken te vangen."
"chart_data_export": {
"description": "Gegevensexport voor dashboardintegraties",
"long_description": "Deze binaire sensor roept de get_chartdata-service aan om gegevens voor dashboard-widgets te exporteren. Ondersteunt ApexCharts en andere dashboardoplossingen die prijsgegevens willen visualiseren.",
"usage_tips": "Configureer de YAML-parameters in de integratieopties onder 'Geavanceerd'. Deze sensor biedt meestal geen praktische waarde in automatiseringen - hij dient hoofdzakelijk als servicecontainer voor dashboardgebruik. Raadpleeg de documentatie voor specifieke parameterformat."
}
},
"home_types": {
@ -569,15 +482,5 @@
"HOUSE": "Huis",
"COTTAGE": "Huisje"
},
"time_units": {
"day": "{count} dag",
"days": "{count} dagen",
"hour": "{count} uur",
"hours": "{count} uur",
"minute": "{count} minuut",
"minutes": "{count} minuten",
"ago": "{parts} geleden",
"now": "nu"
},
"attribution": "Gegevens geleverd door Tibber"
}

View file

@ -1,20 +1,7 @@
{
"apexcharts": {
"title_rating_level": "Prisfaser dagsprogress",
"title_level": "Prisnivå",
"hourly_suffix": "(Ø per timme)",
"best_price_period_name": "Bästa prisperiod",
"peak_price_period_name": "Toppprisperiod",
"notification": {
"metadata_sensor_unavailable": {
"title": "Tibber Prices: ApexCharts YAML genererad med begränsad funktionalitet",
"message": "Du har precis genererat en ApexCharts-kortkonfiguration via Utvecklarverktyg. Diagram-metadata-sensorn är inaktiverad, så den genererade YAML:en visar bara **grundläggande funktionalitet** (auto-skalning, fast gradient vid 50%).\n\n**För full funktionalitet** (optimerad skalning, dynamiska gradientfärger):\n1. [Öppna Tibber Prices-integrationen](https://my.home-assistant.io/redirect/integration/?domain=tibber_prices)\n2. Aktivera 'Chart Metadata'-sensorn\n3. **Generera YAML:en igen** via Utvecklarverktyg\n4. **Ersätt den gamla YAML:en** i din instrumentpanel med den nya versionen\n\n⚠ Det räcker inte att bara aktivera sensorn - du måste regenerera och ersätta YAML-koden!"
},
"missing_cards": {
"title": "Tibber Prices: ApexCharts YAML kan inte användas",
"message": "Du har precis genererat en ApexCharts-kortkonfiguration via Utvecklarverktyg, men den genererade YAML:en **kommer inte att fungera** eftersom nödvändiga anpassade kort saknas.\n\n**Saknade kort:**\n{cards}\n\n**För att använda den genererade YAML:en:**\n1. Klicka på länkarna ovan för att installera de saknade korten från HACS\n2. Starta om Home Assistant (ibland nödvändigt)\n3. **Generera YAML:en igen** via Utvecklarverktyg\n4. Lägg till YAML:en i din instrumentpanel\n\n⚠ Den nuvarande YAML-koden fungerar inte förrän alla kort är installerade!"
}
}
"title_rating_level": "Prisfaser daglig framsteg",
"title_level": "Prisnivå"
},
"sensor": {
"current_interval_price": {
@ -22,7 +9,7 @@
"long_description": "Visar nuvarande pris per kWh från ditt Tibber-abonnemang",
"usage_tips": "Använd detta för att spåra priser eller skapa automationer som körs när el är billig"
},
"current_interval_price_base": {
"current_interval_price_major": {
"description": "Nuvarande elpris i huvudvaluta (EUR/kWh, NOK/kWh, osv.) för Energipanelen",
"long_description": "Visar nuvarande pris per kWh i huvudvaluta-enheter (t.ex. EUR/kWh istället för ct/kWh, NOK/kWh istället för øre/kWh). Denna sensor är speciellt utformad för användning med Home Assistants Energipanel, som kräver priser i standardvalutaenheter.",
"usage_tips": "Använd denna sensor när du konfigurerar Energipanelen under Inställningar → Instrumentpaneler → Energi. Välj denna sensor som 'Entitet med nuvarande pris' för att automatiskt beräkna dina energikostnader. Energipanelen multiplicerar din energiförbrukning (kWh) med detta pris för att visa totala kostnader."
@ -58,9 +45,9 @@
"usage_tips": "Använd detta för att undvika att köra apparater under topppristider"
},
"average_price_today": {
"description": "Typiskt elpris för idag per kWh (konfigurerbart visningsformat)",
"long_description": "Visar priset per kWh för nuvarande dag från ditt Tibber-abonnemang. **Som standard visar statusen medianen** (motståndskraftig mot extrema prispikar, visar typisk prisnåvå). Du kan ändra detta i integrationsinstllningarna för att visa det aritmetiska medelvärdet istället. Det alternativa värdet är tillgängligt som attribut.",
"usage_tips": "Använd detta som baslinje för att jämföra nuvarande priser. För beräkningar använd: {{ state_attr('sensor.average_price_today', 'price_mean') }}"
"description": "Det genomsnittliga elpriset för idag per kWh",
"long_description": "Visar genomsnittspriset per kWh för nuvarande dag från ditt Tibber-abonnemang",
"usage_tips": "Använd detta som baslinje för att jämföra nuvarande priser"
},
"lowest_price_tomorrow": {
"description": "Det lägsta elpriset för imorgon per kWh",
@ -73,9 +60,9 @@
"usage_tips": "Använd detta för att undvika att köra apparater under morgondagens topppristider. Användbart för att planera runt dyra perioder."
},
"average_price_tomorrow": {
"description": "Typiskt elpris för imorgon per kWh (konfigurerbart visningsformat)",
"long_description": "Visar priset per kWh för morgondagen från ditt Tibber-abonnemang. **Som standard visar statusen medianen** (motståndskraftig mot extrema prispikar). Du kan ändra detta i integrationsinstllningarna för att visa det aritmetiska medelvärdet istället. Det alternativa värdet är tillgängligt som attribut. Denna sensor blir otillgänglig tills morgondagens data publiceras av Tibber (vanligtvis runt 13:00-14:00 CET).",
"usage_tips": "Använd detta som baslinje för att jämföra morgondagens priser och planera konsumtion. Jämför med dagens median för att se om morgondagen kommer att bli dyrare eller billigare totalt sett."
"description": "Det genomsnittliga elpriset för imorgon per kWh",
"long_description": "Visar genomsnittspriset per kWh för morgondagen från ditt Tibber-abonnemang. Denna sensor blir otillgänglig tills morgondagens data publiceras av Tibber (vanligtvis runt 13:00-14:00 CET).",
"usage_tips": "Använd detta som baslinje för att jämföra morgondagens priser och planera konsumtion. Jämför med dagens genomsnitt för att se om morgondagen kommer att bli dyrare eller billigare totalt sett."
},
"yesterday_price_level": {
"description": "Aggregerad prisnivå för igår",
@ -108,14 +95,14 @@
"usage_tips": "Använd detta för att planera imorgonens energiförbrukning baserat på dina personliga priströskelvärden. Jämför med idag för att avgöra om du ska skjuta upp förbrukning till imorgon eller använda energi idag."
},
"trailing_price_average": {
"description": "Typiskt elpris för de senaste 24 timmarna per kWh (konfigurerbart visningsformat)",
"long_description": "Visar priset per kWh beräknat från de senaste 24 timmarna. **Som standard visar statusen medianen** (motståndskraftig mot extrema prispikar, visar typisk prisnåvå). Du kan ändra detta i integrationsinstllningarna för att visa det aritmetiska medelvärdet istället. Det alternativa värdet är tillgängligt som attribut. Uppdateras var 15:e minut.",
"usage_tips": "Använd statusvärdet för att se den typiska nuvarande prisnåvån. För kostnadsberäkningar använd: {{ state_attr('sensor.trailing_price_average', 'price_mean') }}"
"description": "Det genomsnittliga elpriset för de senaste 24 timmarna per kWh",
"long_description": "Visar genomsnittspriset per kWh beräknat från de senaste 24 timmarna (rullande genomsnitt) från ditt Tibber-abonnemang. Detta ger ett rullande genomsnitt som uppdateras var 15:e minut baserat på historiska data.",
"usage_tips": "Använd detta för att jämföra nuvarande priser mot senaste trender. Ett nuvarande pris som ligger väsentligt över detta genomsnitt kan indikera ett bra tillfälle att minska konsumtionen."
},
"leading_price_average": {
"description": "Typiskt elpris för nästa 24 timmar per kWh (konfigurerbart visningsformat)",
"long_description": "Visar priset per kWh beräknat från nästa 24 timmar. **Som standard visar statusen medianen** (motståndskraftig mot extrema prispikar, visar förväntad prisnåvå). Du kan ändra detta i integrationsinstllningarna för att visa det aritmetiska medelvärdet istället. Det alternativa värdet är tillgängligt som attribut.",
"usage_tips": "Använd statusvärdet för att se den typiska kommande prisnåvån. För kostnadsberäkningar använd: {{ state_attr('sensor.leading_price_average', 'price_mean') }}"
"description": "Det genomsnittliga elpriset för nästa 24 timmar per kWh",
"long_description": "Visar genomsnittspriset per kWh beräknat från nästa 24 timmar (framåtblickande genomsnitt) från ditt Tibber-abonnemang. Detta ger ett framåtblickande genomsnitt baserat på tillgängliga prognosdata.",
"usage_tips": "Använd detta för att planera energianvändning. Om nuvarande pris är under det framåtblickande genomsnittet kan det vara ett bra tillfälle att köra energikrävande apparater."
},
"trailing_price_min": {
"description": "Det minsta elpriset för de senaste 24 timmarna per kWh",
@ -292,74 +279,64 @@
"long_description": "Visar tidsstämpeln för det senaste tillgängliga prisdataintervallet från ditt Tibber-abonnemang"
},
"today_volatility": {
"description": "Hur mycket elpriserna varierar idag",
"long_description": "Visar om dagens priser är stabila eller har stora svängningar. Låg volatilitet innebär ganska jämna priser timing spelar liten roll. Hög volatilitet innebär tydliga prisskillnader under dagen bra tillfälle att flytta förbrukning till billigare perioder. `price_coefficient_variation_%` visar procentvärdet, `price_spread` visar den absoluta prisspannet.",
"usage_tips": "Använd detta för att avgöra om optimering är värt besväret. Vid låg volatilitet kan du köra enheter när som helst. Vid hög volatilitet sparar du märkbart genom att följa Best Price-perioder."
"description": "Prisvolatilitetsklassificering för idag",
"long_description": "Visar hur mycket elpriserna varierar under dagen baserat på spridningen (skillnaden mellan högsta och lägsta pris). Klassificering: LÅG = spridning < 5 öre, MÅTTLIG = 5-15 öre, HÖG = 15-30 öre, MYCKET HÖG = >30 öre.",
"usage_tips": "Använd detta för att avgöra om prisbaserad optimering är värt besväret. Till exempel, med ett balkongbatteri som har 15% effektivitetsförlust är optimering endast meningsfull när volatiliteten är åtminstone MÅTTLIG. Skapa automationer som kontrollerar volatiliteten innan laddnings-/urladdningscykler planeras."
},
"tomorrow_volatility": {
"description": "Hur mycket elpriserna kommer att variera i morgon",
"long_description": "Visar om priserna i morgon blir stabila eller får stora svängningar. Tillgänglig när morgondagens data är publicerad (vanligen 13:0014:00 CET). Låg volatilitet innebär ganska jämna priser timing är inte kritisk. Hög volatilitet innebär tydliga prisskillnader under dagen bra läge att planera energikrävande uppgifter. `price_coefficient_variation_%` visar procentvärdet, `price_spread` visar den absoluta prisspannet.",
"usage_tips": "Använd för att planera morgondagens förbrukning. Hög volatilitet? Planera flexibla laster i Best Price-perioder. Låg volatilitet? Kör enheter när det passar dig."
"description": "Prisvolatilitetsklassificering för imorgon",
"long_description": "Visar hur mycket elpriserna kommer att variera under morgondagen baserat på spridningen (skillnaden mellan högsta och lägsta pris). Blir otillgänglig tills morgondagens data publiceras (vanligtvis 13:00-14:00 CET).",
"usage_tips": "Använd detta för förhandsplanering av morgondagens energianvändning. Om morgondagen har HÖG eller MYCKET HÖG volatilitet är det värt att optimera energiförbrukningstiming. Vid LÅG volatilitet kan du köra enheter när som helst utan betydande kostnadsskillnader."
},
"next_24h_volatility": {
"description": "Hur mycket priserna varierar de kommande 24 timmarna",
"long_description": "Visar prisvolatilitet för ett rullande 24-timmarsfönster från nu (uppdateras var 15:e minut). Låg volatilitet innebär ganska jämna priser. Hög volatilitet innebär märkbara prissvängningar och därmed optimeringsmöjligheter. Till skillnad från idag/i morgon-sensorer korsar den här dagsgränser och ger en kontinuerlig framåtblickande bedömning. `price_coefficient_variation_%` visar procentvärdet, `price_spread` visar den absoluta prisspannet.",
"usage_tips": "Bäst för beslut i realtid. Använd vid planering av batteriladdning eller andra flexibla laster som kan gå över midnatt. Ger en konsekvent 24h-bild oberoende av kalenderdag."
"description": "Prisvolatilitetsklassificering för rullande nästa 24 timmar",
"long_description": "Visar hur mycket elpriserna varierar under de nästa 24 timmarna från nu (rullande fönster). Detta korsar daggränser och uppdateras var 15:e minut, vilket ger en framåtblickande volatilitetsbedömning oberoende av kalenderdagar.",
"usage_tips": "Bästa sensorn för realtidsoptimeringsbeslut. Till skillnad från idag/imorgon-sensorer som växlar vid midnatt ger detta en kontinuerlig 24t volatilitetsbedömning. Använd för batteriladningsstrategier som sträcker sig över daggränser."
},
"today_tomorrow_volatility": {
"description": "Kombinerad prisvolatilitet för idag och imorgon",
"long_description": "Visar den samlade volatiliteten när idag och imorgon ses tillsammans (när morgondatan finns). Visar om det finns tydliga prisskillnader över dagsgränsen. Faller tillbaka till endast idag om morgondatan saknas. Nyttig för flerdagarsoptimering. `price_coefficient_variation_%` visar procentvärdet, `price_spread` visar den absoluta prisspannet.",
"usage_tips": "Använd för uppgifter som sträcker sig över flera dagar. Kontrollera om prisskillnaderna är stora nog för att planera efter. De enskilda dag-sensorerna visar bidrag per dag om du behöver mer detaljer."
"description": "Kombinerad prisvolatilitetsklassificering för idag och imorgon",
"long_description": "Visar volatilitet över både idag och imorgon kombinerat (när morgondagens data är tillgänglig). Ger en utökad vy av prisvariationen som sträcker sig upp till 48 timmar. Faller tillbaka på endast idag när morgondagens data inte är tillgänglig än.",
"usage_tips": "Använd detta för flerdagarsplanering och för att förstå om prismöjligheter finns över daggränsen. 'today_volatility' och 'tomorrow_volatility' uppdelningsattributen visar individuella dagsbidrag. Användbart för planering av laddningssessioner som kan sträcka sig över midnatt."
},
"data_lifecycle_status": {
"description": "Gjeldende tilstand for prisdatalivssyklus og hurtigbufring",
"long_description": "Viser om integrasjonen bruker hurtigbufrede data eller ferske data fra API-et. Viser gjeldende livssyklustilstand: 'cached' (bruker lagrede data), 'fresh' (nettopp hentet fra API), 'refreshing' (henter for øyeblikket), 'searching_tomorrow' (søker aktivt etter morgendagens data etter 13:00), 'turnover_pending' (innen 15 minutter før midnatt, 23:45-00:00), eller 'error' (henting mislyktes). Inkluderer omfattende attributter som cache-alder, neste API-spørring, datafullstendighet og API-anropsstatistikk.",
"usage_tips": "Bruk denne diagnosesensoren for å forstå dataferskhet og API-anropsmønstre. Sjekk 'cache_age'-attributtet for å se hvor gamle de nåværende dataene er. Overvåk 'next_api_poll' for å vite når neste oppdatering er planlagt. Bruk 'data_completeness' for å se om data for i går/i dag/i morgen er tilgjengelig. 'api_calls_today'-telleren hjelper med å spore API-bruk. Perfekt for feilsøking eller forståelse av integrasjonens oppførsel."
"price_forecast": {
"description": "Prognos för kommande elpriser",
"long_description": "Visar kommande elpriser för framtida intervaller i ett format som är enkelt att använda i instrumentpaneler",
"usage_tips": "Använd denna enhets attribut för att visa kommande priser i diagram eller anpassade kort. Få åtkomst till antingen 'intervals' för alla framtida intervaller eller 'hours' för timvisa sammanfattningar."
},
"best_price_end_time": {
"description": "Total längd för nuvarande eller nästa billigperiod (state i timmar, attribut i minuter)",
"long_description": "Visar hur länge billigperioden varar. State använder timmar (decimal) för en läsbar UI; attributet `period_duration_minutes` behåller avrundade minuter för automationer. Aktiv → varaktighet för aktuell period, annars nästa.",
"usage_tips": "UI kan visa 1,5 h medan `period_duration_minutes` = 90 för automationer."
},
"best_price_period_duration": {
"description": "Längd på nuvarande/nästa billigperiod",
"long_description": "Total längd av nuvarande eller nästa billigperiod. State visas i timmar (t.ex. 1,5 h) för enkel avläsning i UI, medan attributet `period_duration_minutes` ger samma värde i minuter (t.ex. 90) för automationer. Detta värde representerar den **fullständigt planerade längden** av perioden och är konstant under hela perioden, även när återstående tid (remaining_minutes) minskar.",
"usage_tips": "Kombinera med remaining_minutes för att beräkna när långvariga enheter ska stoppas: Perioden startade för `period_duration_minutes - remaining_minutes` minuter sedan. Detta attribut stöder energioptimeringsstrategier genom att hjälpa till med att planera högförbruksaktiviteter inom billiga perioder."
"description": "När nuvarande eller nästa billigperiod slutar",
"long_description": "Visar sluttidsstämpeln för nuvarande billigperiod när aktiv, eller slutet av nästa period när ingen period är aktiv. Visar alltid en användbar tidsreferens för planering. Returnerar 'Okänt' endast när inga perioder är konfigurerade.",
"usage_tips": "Använd detta för att visa en nedräkning som 'Billigperiod slutar om 2 timmar' (när aktiv) eller 'Nästa billigperiod slutar kl 14:00' (när inaktiv). Home Assistant visar automatiskt relativ tid för tidsstämpelsensorer."
},
"best_price_remaining_minutes": {
"description": "Tid kvar i nuvarande billigperiod",
"long_description": "Visar hur mycket tid som återstår i nuvarande billigperiod. State visas i timmar (t.ex. 0,75 h) för enkel avläsning i instrumentpaneler, medan attributet `remaining_minutes` ger samma tid i minuter (t.ex. 45) för automationsvillkor. **Nedräkningstimer**: Detta värde minskar varje minut under en aktiv period. Returnerar 0 när ingen billigperiod är aktiv. Uppdateras varje minut.",
"usage_tips": "För automationer: Använd attribut `remaining_minutes` som 'Om remaining_minutes > 60, starta diskmaskin nu (tillräckligt med tid för att slutföra)' eller 'Om remaining_minutes < 15, avsluta nuvarande cykel snart'. UI visar användarvänliga timmar (t.ex. 1,25 h). Värde 0 indikerar ingen aktiv billigperiod."
"description": "Återstående minuter i nuvarande billigperiod (0 när inaktiv)",
"long_description": "Visar hur många minuter som återstår i nuvarande billigperiod. Returnerar 0 när ingen period är aktiv. Uppdateras varje minut. Kontrollera binary_sensor.best_price_period för att se om en period är aktiv.",
"usage_tips": "Perfekt för automationer: 'Om remaining_minutes > 0 OCH remaining_minutes < 30, starta tvättmaskin nu'. Värdet 0 gör det enkelt att kontrollera om en period är aktiv (värde > 0) eller inte (värde = 0)."
},
"best_price_progress": {
"description": "Framsteg genom nuvarande billigperiod (0% när inaktiv)",
"long_description": "Visar framsteg genom nuvarande billigperiod som 0-100%. Returnerar 0% när ingen period är aktiv. Uppdateras varje minut. 0% betyder att perioden just startade, 100% betyder att den snart slutar.",
"usage_tips": "Perfekt för visuella framstegsindikatorer. Använd i automationer: 'Om progress > 0 OCH progress > 75, skicka avisering om att billigperioden snart slutar'. Värde 0 indikerar ingen aktiv period."
"long_description": "Visar framsteg genom nuvarande billigperiod som 0-100%. Returnerar 0% när ingen period är aktiv. Uppdateras varje minut. 0% betyder period just startad, 100% betyder den snart slutar.",
"usage_tips": "Bra för visuella framstegsstaplar. Använd i automationer: 'Om progress > 0 OCH progress > 75, skicka meddelande att billigperiod snart slutar'. Värde 0 indikerar ingen aktiv period."
},
"best_price_next_start_time": {
"description": "Total längd för nuvarande eller nästa dyrperiod (state i timmar, attribut i minuter)",
"long_description": "Visar hur länge den dyra perioden varar. State använder timmar (decimal) för UI; attributet `period_duration_minutes` behåller avrundade minuter för automationer. Aktiv → varaktighet för aktuell period, annars nästa.",
"usage_tips": "UI kan visa 0,75 h medan `period_duration_minutes` = 45 för automationer."
"description": "När nästa billigperiod startar",
"long_description": "Visar när nästa kommande billigperiod startar. Under en aktiv period visar detta starten av NÄSTA period efter den nuvarande. Returnerar 'Okänt' endast när inga framtida perioder är konfigurerade.",
"usage_tips": "Alltid användbart för framåtplanering: 'Nästa billigperiod startar om 3 timmar' (oavsett om du är i en period nu eller inte). Kombinera med automationer: 'När nästa starttid är om 10 minuter, skicka meddelande för att förbereda tvättmaskin'."
},
"best_price_next_in_minutes": {
"description": "Tid kvar i nuvarande dyrperiod (state i timmar, attribut i minuter)",
"long_description": "Visar hur mycket tid som återstår. State använder timmar (decimal); attributet `remaining_minutes` behåller avrundade minuter för automationer. Returnerar 0 när ingen period är aktiv. Uppdateras varje minut.",
"usage_tips": "Använd `remaining_minutes` för trösklar (t.ex. > 60) medan state är lätt att läsa i timmar."
"description": "Minuter tills nästa billigperiod startar (0 vid övergång)",
"long_description": "Visar minuter tills nästa billigperiod startar. Under en aktiv period visar detta tiden till perioden EFTER den nuvarande. Returnerar 0 under korta övergångsmoment. Uppdateras varje minut.",
"usage_tips": "Perfekt för 'vänta tills billigperiod' automationer: 'Om next_in_minutes > 0 OCH next_in_minutes < 15, vänta innan diskmaskin startas'. Värde > 0 indikerar alltid att en framtida period är planerad."
},
"peak_price_end_time": {
"description": "Tid tills nästa dyrperiod startar (state i timmar, attribut i minuter)",
"long_description": "Visar hur länge tills nästa dyrperiod startar. State använder timmar (decimal); attributet `next_in_minutes` behåller avrundade minuter för automationer. Under en aktiv period visar detta tiden till perioden efter den aktuella. 0 under korta övergångar. Uppdateras varje minut.",
"usage_tips": "Använd `next_in_minutes` i automationer (t.ex. < 10) medan state är lätt att läsa i timmar."
},
"peak_price_period_duration": {
"description": "Längd på nuvarande/nästa dyrperiod",
"long_description": "Total längd av nuvarande eller nästa dyrperiod. State visas i timmar (t.ex. 1,5 h) för enkel avläsning i UI, medan attributet `period_duration_minutes` ger samma värde i minuter (t.ex. 90) för automationer. Detta värde representerar den **fullständigt planerade längden** av perioden och är konstant under hela perioden, även när återstående tid (remaining_minutes) minskar.",
"usage_tips": "Kombinera med remaining_minutes för att beräkna när långvariga enheter ska stoppas: Perioden startade för `period_duration_minutes - remaining_minutes` minuter sedan. Detta attribut stöder energibesparingsstrategier genom att hjälpa till med att planera högförbruksaktiviteter utanför dyra perioder."
"description": "När nuvarande eller nästa dyrperiod slutar",
"long_description": "Visar sluttidsstämpeln för nuvarande dyrperiod när aktiv, eller slutet av nästa period när ingen period är aktiv. Visar alltid en användbar tidsreferens för planering. Returnerar 'Okänt' endast när inga perioder är konfigurerade.",
"usage_tips": "Använd detta för att visa 'Dyrperiod slutar om 1 timme' (när aktiv) eller 'Nästa dyrperiod slutar kl 18:00' (när inaktiv). Kombinera med automationer för att återuppta drift efter topp."
},
"peak_price_remaining_minutes": {
"description": "Tid kvar i nuvarande dyrperiod",
"long_description": "Visar hur mycket tid som återstår i nuvarande dyrperiod. State visas i timmar (t.ex. 0,75 h) för enkel avläsning i instrumentpaneler, medan attributet `remaining_minutes` ger samma tid i minuter (t.ex. 45) för automationsvillkor. **Nedräkningstimer**: Detta värde minskar varje minut under en aktiv period. Returnerar 0 när ingen dyrperiod är aktiv. Uppdateras varje minut.",
"usage_tips": "För automationer: Använd attribut `remaining_minutes` som 'Om remaining_minutes > 60, avbryt uppskjuten laddningssession' eller 'Om remaining_minutes < 15, återuppta normal drift snart'. UI visar användarvänliga timmar (t.ex. 1,0 h). Värde 0 indikerar ingen aktiv dyrperiod."
"description": "Återstående minuter i nuvarande dyrperiod (0 när inaktiv)",
"long_description": "Visar hur många minuter som återstår i nuvarande dyrperiod. Returnerar 0 när ingen period är aktiv. Uppdateras varje minut. Kontrollera binary_sensor.peak_price_period för att se om en period är aktiv.",
"usage_tips": "Använd i automationer: 'Om remaining_minutes > 60, avbryt uppskjuten laddningssession'. Värde 0 gör det enkelt att skilja mellan aktiva (värde > 0) och inaktiva (värde = 0) perioder."
},
"peak_price_progress": {
"description": "Framsteg genom nuvarande dyrperiod (0% när inaktiv)",
@ -372,9 +349,19 @@
"usage_tips": "Alltid användbart för planering: 'Nästa dyrperiod startar om 2 timmar'. Automation: 'När nästa starttid är om 30 minuter, minska värmetemperatur förebyggande'."
},
"peak_price_next_in_minutes": {
"description": "Tid till nästa dyrperiod",
"long_description": "Visar hur länge till nästa dyrperiod. State visas i timmar (t.ex. 0,5 h) för instrumentpaneler, medan attributet `next_in_minutes` ger minuter (t.ex. 30) för automationsvillkor. Under en aktiv period visar detta tiden till perioden EFTER den nuvarande. Returnerar 0 under korta övergångsmoment. Uppdateras varje minut.",
"usage_tips": "För automationer: Använd attribut `next_in_minutes` som 'Om next_in_minutes > 0 OCH next_in_minutes < 10, slutför nuvarande laddcykel nu innan priserna ökar'. Värde > 0 indikerar alltid att en framtida dyrperiod är planerad."
"description": "Minuter tills nästa dyrperiod startar (0 vid övergång)",
"long_description": "Visar minuter tills nästa dyrperiod startar. Under en aktiv period visar detta tiden till perioden EFTER den nuvarande. Returnerar 0 under korta övergångsmoment. Uppdateras varje minut.",
"usage_tips": "Förebyggande automation: 'Om next_in_minutes > 0 OCH next_in_minutes < 10, slutför nuvarande laddcykel nu innan priserna ökar'."
},
"best_price_period_duration": {
"description": "Total längd på nuvarande eller nästa billigperiod i minuter",
"long_description": "Visar den totala längden på billigperioden i minuter. Under en aktiv period visar detta hela längden av nuvarande period. När ingen period är aktiv visar detta längden på nästa kommande period. Exempel: '90 minuter' för en 1,5-timmars period.",
"usage_tips": "Kombinera med remaining_minutes för att planera uppgifter: 'Om duration = 120 OCH remaining_minutes > 90, starta tvättmaskin (tillräckligt med tid för att slutföra)'. Användbart för att förstå om perioder är tillräckligt långa för energikrävande uppgifter."
},
"peak_price_period_duration": {
"description": "Total längd på nuvarande eller nästa dyrperiod i minuter",
"long_description": "Visar den totala längden på dyrperioden i minuter. Under en aktiv period visar detta hela längden av nuvarande period. När ingen period är aktiv visar detta längden på nästa kommande period. Exempel: '60 minuter' för en 1-timmars period.",
"usage_tips": "Använd för att planera energisparåtgärder: 'Om duration > 120, minska värmetemperatur mer aggressivt (lång dyr period)'. Hjälper till att bedöma hur mycket energiförbrukning måste minskas."
},
"home_type": {
"description": "Bostadstyp (lägenhet, hus osv.)",
@ -447,14 +434,9 @@
"usage_tips": "Använd detta för att övervaka din abonnemangsstatus. Ställ in varningar om statusen ändras från 'Aktiv' för att säkerställa oavbruten service."
},
"chart_data_export": {
"description": "Dataexport för dashboard-integrationer",
"long_description": "Denna sensor anropar get_chartdata-tjänsten med din konfigurerade YAML-konfiguration och exponerar resultatet som entitetsattribut. Statusen visar 'ready' när data är tillgänglig, 'error' vid fel, eller 'pending' före första anropet. Perfekt för dashboard-integrationer som ApexCharts som behöver läsa prisdata från entitetsattribut.",
"usage_tips": "Konfigurera YAML-parametrarna i integrationsalternativen för att matcha ditt get_chartdata-tjänstanrop. Sensorn uppdateras automatiskt när prisdata uppdateras (vanligtvis efter midnatt och när morgondagens data anländer). Få tillgång till tjänstesvarsdata direkt från entitetens attribut - strukturen matchar exakt vad get_chartdata returnerar."
},
"chart_metadata": {
"description": "Lättviktig metadata för diagramkonfiguration",
"long_description": "Tillhandahåller väsentliga diagramkonfigurationsvärden som sensorattribut. Användbart för vilket diagramkort som helst som behöver Y-axelgränser. Sensorn anropar get_chartdata med endast-metadata-läge (ingen databehandling) och extraherar: yaxis_min, yaxis_max (föreslagen Y-axelomfång för optimal skalning). Statusen återspeglar tjänstanropsresultatet: 'ready' vid framgång, 'error' vid fel, 'pending' under initialisering.",
"usage_tips": "Konfigurera via configuration.yaml under tibber_prices.chart_metadata_config (valfritt: day, subunit_currency, resolution). Sensorn uppdateras automatiskt vid pris dataändringar. Få tillgång till metadata från attribut: yaxis_min, yaxis_max. Använd med config-template-card eller vilket verktyg som helst som läser entitetsattribut - perfekt för dynamisk diagramkonfiguration utan manuella beräkningar."
"description": "Dataexport för instrumentpanelsintegrationer",
"long_description": "Denna sensor anropar get_chartdata-tjänsten med din konfigurerade YAML-konfiguration och exponerar resultatet som entitetsattribut. Statusen visar 'ready' när data är tillgänglig, 'error' vid fel, eller 'pending' före första anropet. Perfekt för instrumentpanelsintegrationer som ApexCharts som behöver läsa prisdata från entitetsattribut.",
"usage_tips": "Konfigurera YAML-parametrarna i integrationsinställningarna för att matcha ditt get_chartdata-tjänsteanrop. Sensorn uppdateras automatiskt när prisdata uppdateras (vanligtvis efter midnatt och när morgondagens data anländer). Få åtkomst till tjänstesvarsdata direkt från entitetens attribut - strukturen matchar exakt vad get_chartdata returnerar."
}
},
"binary_sensor": {
@ -487,80 +469,11 @@
"description": "Om realtidsförbrukningsövervakning är aktiv",
"long_description": "Indikerar om realtidsövervakning av elförbrukning är aktiverad och aktiv för ditt Tibber-hem. Detta kräver kompatibel mätutrustning (t.ex. Tibber Pulse) och en aktiv prenumeration.",
"usage_tips": "Använd detta för att verifiera att realtidsförbrukningen är tillgänglig. Aktivera meddelanden om detta oväntat ändras till 'av', vilket indikerar potentiella hårdvaru- eller anslutningsproblem."
}
},
"number": {
"best_price_flex_override": {
"description": "Maximal procent över daglig minimumpris som intervaller kan ha och fortfarande kvalificera som 'bästa pris'. Rekommenderas: 15-20 med lättnad aktiverad (standard), eller 25-35 utan lättnad. Maximum: 50 (hårt tak för tillförlitlig perioddetektering).",
"long_description": "När denna entitet är aktiverad överskriver värdet 'Flexibilitet'-inställningen från alternativ-dialogen för bästa pris-periodberäkningar.",
"usage_tips": "Aktivera denna entitet för att dynamiskt justera bästa pris-detektering via automatiseringar, t.ex. högre flexibilitet för kritiska laster eller striktare krav för flexibla apparater."
},
"best_price_min_distance_override": {
"description": "Minsta procentuella avstånd under dagligt genomsnitt. Intervaller måste vara så långt under genomsnittet för att kvalificera som 'bästa pris'. Hjälper att skilja äkta lågprisperioder från genomsnittspriser.",
"long_description": "När denna entitet är aktiverad överskriver värdet 'Minimiavstånd'-inställningen från alternativ-dialogen för bästa pris-periodberäkningar.",
"usage_tips": "Öka värdet för striktare bästa pris-kriterier. Minska om för få perioder detekteras."
},
"best_price_min_period_length_override": {
"description": "Minsta periodlängd i 15-minuters intervaller. Perioder kortare än detta rapporteras inte. Exempel: 2 = minst 30 minuter.",
"long_description": "När denna entitet är aktiverad överskriver värdet 'Minsta periodlängd'-inställningen från alternativ-dialogen för bästa pris-periodberäkningar.",
"usage_tips": "Anpassa till typisk apparatkörtid: 2 (30 min) för snabbprogram, 4-8 (1-2 timmar) för normala cykler, 8+ för långa ECO-program."
},
"best_price_min_periods_override": {
"description": "Minsta antal bästa pris-perioder att hitta dagligen. När lättnad är aktiverad kommer systemet automatiskt att justera kriterierna för att uppnå detta antal.",
"long_description": "När denna entitet är aktiverad överskriver värdet 'Minsta antal perioder'-inställningen från alternativ-dialogen för bästa pris-periodberäkningar.",
"usage_tips": "Ställ in detta på antalet tidskritiska uppgifter du har dagligen. Exempel: 2 för två tvattmaskinskörningar."
},
"best_price_relaxation_attempts_override": {
"description": "Antal försök att gradvis lätta på kriterierna för att uppnå minsta periodantal. Varje försök ökar flexibiliteten med 3 procent. Vid 0 används endast baskriterier.",
"long_description": "När denna entitet är aktiverad överskriver värdet 'Lättnadsförsök'-inställningen från alternativ-dialogen för bästa pris-periodberäkningar.",
"usage_tips": "Högre värden gör perioddetektering mer adaptiv för dagar med stabila priser. Ställ in på 0 för att tvinga strikta kriterier utan lättnad."
},
"best_price_gap_count_override": {
"description": "Maximalt antal dyrare intervaller som kan tillåtas mellan billiga intervaller medan de fortfarande räknas som en sammanhängande period. Vid 0 måste billiga intervaller vara påföljande.",
"long_description": "När denna entitet är aktiverad överskriver värdet 'Glaptolerans'-inställningen från alternativ-dialogen för bästa pris-periodberäkningar.",
"usage_tips": "Öka detta för apparater med variabel last (t.ex. värmepumpar) som kan tolerera korta dyrare intervaller. Ställ in på 0 för kontinuerligt billiga perioder."
},
"peak_price_flex_override": {
"description": "Maximal procent under daglig maximumpris som intervaller kan ha och fortfarande kvalificera som 'topppris'. Samma rekommendationer som för bästa pris-flexibilitet.",
"long_description": "När denna entitet är aktiverad överskriver värdet 'Flexibilitet'-inställningen från alternativ-dialogen för topppris-periodberäkningar.",
"usage_tips": "Använd detta för att justera topppris-tröskeln vid körtid för automatiseringar som undviker förbrukning under dyra timmar."
},
"peak_price_min_distance_override": {
"description": "Minsta procentuella avstånd över dagligt genomsnitt. Intervaller måste vara så långt över genomsnittet för att kvalificera som 'topppris'.",
"long_description": "När denna entitet är aktiverad överskriver värdet 'Minimiavstånd'-inställningen från alternativ-dialogen för topppris-periodberäkningar.",
"usage_tips": "Öka värdet för att endast fånga extrema pristoppar. Minska för att inkludera fler högpristider."
},
"peak_price_min_period_length_override": {
"description": "Minsta periodlängd i 15-minuters intervaller för topppriser. Kortare pristoppar rapporteras inte som perioder.",
"long_description": "När denna entitet är aktiverad överskriver värdet 'Minsta periodlängd'-inställningen från alternativ-dialogen för topppris-periodberäkningar.",
"usage_tips": "Kortare värden fångar korta pristoppar. Längre värden fokuserar på ihållande högprisperioder."
},
"peak_price_min_periods_override": {
"description": "Minsta antal topppris-perioder att hitta dagligen.",
"long_description": "När denna entitet är aktiverad överskriver värdet 'Minsta antal perioder'-inställningen från alternativ-dialogen för topppris-periodberäkningar.",
"usage_tips": "Ställ in detta baserat på hur många högprisperioder du vill fånga per dag för automatiseringar."
},
"peak_price_relaxation_attempts_override": {
"description": "Antal försök att lätta på kriterierna för att uppnå minsta antal topppris-perioder.",
"long_description": "När denna entitet är aktiverad överskriver värdet 'Lättnadsförsök'-inställningen från alternativ-dialogen för topppris-periodberäkningar.",
"usage_tips": "Öka detta om inga perioder hittas på dagar med stabila priser. Ställ in på 0 för att tvinga strikta kriterier."
},
"peak_price_gap_count_override": {
"description": "Maximalt antal billigare intervaller som kan tillåtas mellan dyra intervaller medan de fortfarande räknas som en topppris-period.",
"long_description": "När denna entitet är aktiverad överskriver värdet 'Glaptolerans'-inställningen från alternativ-dialogen för topppris-periodberäkningar.",
"usage_tips": "Högre värden fångar längre högprisperioder även med korta prisdipp. Ställ in på 0 för strikt sammanhängande topppriser."
}
},
"switch": {
"best_price_enable_relaxation_override": {
"description": "När aktiverad lättas kriterierna automatiskt för att uppnå minsta periodantal. När inaktiverad rapporteras endast perioder som uppfyller strikta kriterier (möjligen noll perioder på dagar med stabila priser).",
"long_description": "När denna entitet är aktiverad överskriver värdet 'Uppnå minimiantal'-inställningen från alternativ-dialogen för bästa pris-periodberäkningar.",
"usage_tips": "Aktivera detta för garanterade dagliga automatiseringsmöjligheter. Inaktivera om du endast vill ha riktigt billiga perioder, även om det innebär inga perioder vissa dagar."
},
"peak_price_enable_relaxation_override": {
"description": "När aktiverad lättas kriterierna automatiskt för att uppnå minsta periodantal. När inaktiverad rapporteras endast äkta pristoppar.",
"long_description": "När denna entitet är aktiverad överskriver värdet 'Uppnå minimiantal'-inställningen från alternativ-dialogen för topppris-periodberäkningar.",
"usage_tips": "Aktivera detta för konsekventa topppris-varningar. Inaktivera för att endast fånga extrema pristoppar."
"chart_data_export": {
"description": "Dataexport för instrumentpanelsintegrationer",
"long_description": "Denna binär sensor anropar tjänsten get_chartdata för att exportera prissensordata i format som är kompatibelt med ApexCharts och andra instrumentpanelskomponenter. Använd denna tillsammans med custom:apexcharts-card för att visa prissensorer på din instrumentpanel.",
"usage_tips": "Konfigurera YAML-parametrarna i integrationens alternativ under 'ApexCharts-datakonfiguration'. Tjänsten kräver en giltig sensorenhet och returnerar formaterad data för kartrendring. Se dokumentationen för tillgängliga parametrar och anpassningsalternativ."
}
},
"home_types": {
@ -569,15 +482,5 @@
"HOUSE": "Hus",
"COTTAGE": "Stuga"
},
"time_units": {
"day": "{count} dag",
"days": "{count} dagar",
"hour": "{count} timme",
"hours": "{count} timmar",
"minute": "{count} minut",
"minutes": "{count} minuter",
"ago": "{parts} sedan",
"now": "nu"
},
"attribution": "Data tillhandahålls av Tibber"
}

View file

@ -11,7 +11,6 @@ if TYPE_CHECKING:
from .api import TibberPricesApiClient
from .coordinator import TibberPricesDataUpdateCoordinator
from .interval_pool import TibberPricesIntervalPool
@dataclass
@ -21,7 +20,6 @@ class TibberPricesData:
client: TibberPricesApiClient
coordinator: TibberPricesDataUpdateCoordinator
integration: Integration
interval_pool: TibberPricesIntervalPool # Shared interval pool per config entry
if TYPE_CHECKING:

View file

@ -22,9 +22,6 @@ async def async_get_config_entry_diagnostics(
"""Return diagnostics for a config entry."""
coordinator = entry.runtime_data.coordinator
# Get period metadata from coordinator data
price_periods = coordinator.data.get("pricePeriods", {}) if coordinator.data else {}
return {
"entry": {
"entry_id": entry.entry_id,
@ -33,46 +30,16 @@ async def async_get_config_entry_diagnostics(
"domain": entry.domain,
"title": entry.title,
"state": str(entry.state),
"home_id": entry.data.get("home_id", ""),
},
"coordinator": {
"last_update_success": coordinator.last_update_success,
"update_interval": str(coordinator.update_interval),
"is_main_entry": coordinator.is_main_entry(),
"data": coordinator.data,
"update_timestamps": {
"price": coordinator._last_price_update.isoformat() if coordinator._last_price_update else None, # noqa: SLF001
"user": coordinator._last_user_update.isoformat() if coordinator._last_user_update else None, # noqa: SLF001
"last_coordinator_update": coordinator._last_coordinator_update.isoformat() # noqa: SLF001
if coordinator._last_coordinator_update # noqa: SLF001
else None,
},
"lifecycle": {
"state": coordinator._lifecycle_state, # noqa: SLF001
"is_fetching": coordinator._is_fetching, # noqa: SLF001
"api_calls_today": coordinator._api_calls_today, # noqa: SLF001
"last_api_call_date": coordinator._last_api_call_date.isoformat() # noqa: SLF001
if coordinator._last_api_call_date # noqa: SLF001
else None,
},
},
"periods": {
"best_price": {
"count": len(price_periods.get("best_price", {}).get("periods", [])),
"metadata": price_periods.get("best_price", {}).get("metadata", {}),
},
"peak_price": {
"count": len(price_periods.get("peak_price", {}).get("periods", [])),
"metadata": price_periods.get("peak_price", {}).get("metadata", {}),
},
},
"config": {
"options": dict(entry.options),
},
"cache_status": {
"user_data_cached": coordinator._cached_user_data is not None, # noqa: SLF001
"has_price_data": coordinator.data is not None and "priceInfo" in (coordinator.data or {}),
"transformer_cache_valid": coordinator._data_transformer._cached_transformed_data is not None, # noqa: SLF001
"period_calculator_cache_valid": coordinator._period_calculator._cached_periods is not None, # noqa: SLF001
},
"error": {
"last_exception": str(coordinator.last_exception) if coordinator.last_exception else None,

View file

@ -44,22 +44,6 @@ class TibberPricesEntity(CoordinatorEntity[TibberPricesDataUpdateCoordinator]):
configuration_url="https://developer.tibber.com/explorer",
)
@property
def available(self) -> bool:
"""
Return if entity is available.
Entity is unavailable when:
- Coordinator has not completed first update (no data yet)
- Coordinator has encountered an error (last_update_success = False)
Note: Auth failures are handled by coordinator's update method,
which raises ConfigEntryAuthFailed and triggers reauth flow.
"""
# Return False if coordinator not ready or has errors
# Return True if coordinator has data (bool conversion handles None/empty)
return self.coordinator.last_update_success and bool(self.coordinator.data)
def _get_device_info(self) -> tuple[str, str | None, str | None]:
"""Get device name, ID and type."""
user_profile = self.coordinator.get_user_profile()
@ -118,10 +102,8 @@ class TibberPricesEntity(CoordinatorEntity[TibberPricesDataUpdateCoordinator]):
return "Tibber Home", None
try:
# Use 'or {}' to handle None values (API may return None during maintenance)
address = self.coordinator.data.get("address") or {}
address1 = str(address.get("address1", ""))
city = str(address.get("city", ""))
address1 = str(self.coordinator.data.get("address", {}).get("address1", ""))
city = str(self.coordinator.data.get("address", {}).get("city", ""))
app_nickname = str(self.coordinator.data.get("appNickname", ""))
home_type = str(self.coordinator.data.get("type", ""))

View file

@ -49,7 +49,7 @@ def build_period_attributes(period_data: dict) -> dict:
}
def add_description_attributes( # noqa: PLR0913, PLR0912
def add_description_attributes( # noqa: PLR0913
attributes: dict,
platform: str,
translation_key: str | None,
@ -61,13 +61,8 @@ def add_description_attributes( # noqa: PLR0913, PLR0912
"""
Add description attributes from custom translations to an existing attributes dict.
The 'description' attribute is always present, but its content changes based on
CONF_EXTENDED_DESCRIPTIONS setting:
- When disabled: Uses short 'description' from translations
- When enabled: Uses 'long_description' from translations (falls back to short if not available)
Additionally, when CONF_EXTENDED_DESCRIPTIONS is enabled, 'usage_tips' is added as
a separate attribute.
Adds description (always), and optionally long_description and usage_tips if
CONF_EXTENDED_DESCRIPTIONS is enabled in config.
This function modifies the attributes dict in-place. By default, descriptions are
added at the END of the dict (after all other attributes). For special cases like
@ -100,27 +95,20 @@ def add_description_attributes( # noqa: PLR0913, PLR0912
# Build description dict
desc_attrs: dict[str, str] = {}
description = get_entity_description(platform, translation_key, language, "description")
if description:
desc_attrs["description"] = description
extended_descriptions = config_entry.options.get(
CONF_EXTENDED_DESCRIPTIONS,
config_entry.data.get(CONF_EXTENDED_DESCRIPTIONS, DEFAULT_EXTENDED_DESCRIPTIONS),
)
# Choose description based on extended_descriptions setting
if extended_descriptions:
# Use long_description as description content (if available)
description = get_entity_description(platform, translation_key, language, "long_description")
if not description:
# Fallback to short description if long_description not available
description = get_entity_description(platform, translation_key, language, "description")
else:
# Use short description
description = get_entity_description(platform, translation_key, language, "description")
long_desc = get_entity_description(platform, translation_key, language, "long_description")
if long_desc:
desc_attrs["long_description"] = long_desc
if description:
desc_attrs["description"] = description
# Add usage_tips as separate attribute if extended_descriptions enabled
if extended_descriptions:
usage_tips = get_entity_description(platform, translation_key, language, "usage_tips")
if usage_tips:
desc_attrs["usage_tips"] = usage_tips
@ -152,7 +140,7 @@ def add_description_attributes( # noqa: PLR0913, PLR0912
attributes[key] = value
async def async_add_description_attributes( # noqa: PLR0913, PLR0912
async def async_add_description_attributes( # noqa: PLR0913
attributes: dict,
platform: str,
translation_key: str | None,
@ -191,45 +179,32 @@ async def async_add_description_attributes( # noqa: PLR0913, PLR0912
# Build description dict
desc_attrs: dict[str, str] = {}
description = await async_get_entity_description(
hass,
platform,
translation_key,
language,
"description",
)
if description:
desc_attrs["description"] = description
extended_descriptions = config_entry.options.get(
CONF_EXTENDED_DESCRIPTIONS,
config_entry.data.get(CONF_EXTENDED_DESCRIPTIONS, DEFAULT_EXTENDED_DESCRIPTIONS),
)
# Choose description based on extended_descriptions setting
if extended_descriptions:
# Use long_description as description content (if available)
description = await async_get_entity_description(
long_desc = await async_get_entity_description(
hass,
platform,
translation_key,
language,
"long_description",
)
if not description:
# Fallback to short description if long_description not available
description = await async_get_entity_description(
hass,
platform,
translation_key,
language,
"description",
)
else:
# Use short description
description = await async_get_entity_description(
hass,
platform,
translation_key,
language,
"description",
)
if long_desc:
desc_attrs["long_description"] = long_desc
if description:
desc_attrs["description"] = description
# Add usage_tips as separate attribute if extended_descriptions enabled
if extended_descriptions:
usage_tips = await async_get_entity_description(
hass,
platform,

View file

@ -2,7 +2,7 @@
Common helper functions for entities across platforms.
This module provides utility functions used by both sensor and binary_sensor platforms:
- Price value conversion (major/subunit currency units)
- Price value conversion (major/minor currency units)
- Translation helpers (price levels, ratings)
- Time-based calculations (rolling hour center index)
@ -14,52 +14,31 @@ from __future__ import annotations
from typing import TYPE_CHECKING
from custom_components.tibber_prices.const import get_display_unit_factor, get_price_level_translation
from custom_components.tibber_prices.const import get_price_level_translation
from custom_components.tibber_prices.utils.average import (
round_to_nearest_quarter_hour,
)
from homeassistant.util import dt as dt_util
if TYPE_CHECKING:
from datetime import datetime
from custom_components.tibber_prices.coordinator.time_service import TibberPricesTimeService
from custom_components.tibber_prices.data import TibberPricesConfigEntry
from homeassistant.config_entries import ConfigEntry
from homeassistant.core import HomeAssistant
def get_price_value(
price: float,
*,
in_euro: bool | None = None,
config_entry: ConfigEntry | TibberPricesConfigEntry | None = None,
) -> float:
def get_price_value(price: float, *, in_euro: bool) -> float:
"""
Convert price based on unit.
NOTE: This function supports two modes for backward compatibility:
1. Legacy mode: in_euro=True/False (hardcoded conversion)
2. New mode: config_entry (config-driven conversion)
New code should use get_display_unit_factor(config_entry) directly.
Args:
price: Price value to convert.
in_euro: (Legacy) If True, return in base currency; if False, in subunit currency.
config_entry: (New) Config entry to get display unit configuration.
price: Price value to convert
in_euro: If True, return price in euros; if False, return in cents/øre
Returns:
Price in requested unit (major or subunit currency units).
Price in requested unit (euros or minor currency units)
"""
# Legacy mode: use in_euro parameter
if in_euro is not None:
return price if in_euro else round(price * 100, 2)
# New mode: use config_entry
if config_entry is not None:
factor = get_display_unit_factor(config_entry)
return round(price * factor, 2)
# Fallback: default to subunit currency (backward compatibility)
return round(price * 100, 2)
return price if in_euro else round((price * 100), 2)
def translate_level(hass: HomeAssistant, level: str) -> str:
@ -114,8 +93,6 @@ def find_rolling_hour_center_index(
all_prices: list[dict],
current_time: datetime,
hour_offset: int,
*,
time: TibberPricesTimeService,
) -> int | None:
"""
Find the center index for the rolling hour window.
@ -124,7 +101,6 @@ def find_rolling_hour_center_index(
all_prices: List of all price interval dictionaries with 'startsAt' key
current_time: Current datetime to find the current interval
hour_offset: Number of hours to offset from current interval (can be negative)
time: TibberPricesTimeService instance (required)
Returns:
Index of the center interval for the rolling hour window, or None if not found
@ -132,13 +108,14 @@ def find_rolling_hour_center_index(
"""
# Round to nearest interval boundary to handle edge cases where HA schedules
# us slightly before the boundary (e.g., 14:59:59.999 → 15:00:00)
target_time = time.round_to_nearest_quarter(current_time)
target_time = round_to_nearest_quarter_hour(current_time)
current_idx = None
for idx, price_data in enumerate(all_prices):
starts_at = time.get_interval_time(price_data)
starts_at = dt_util.parse_datetime(price_data["startsAt"])
if starts_at is None:
continue
starts_at = dt_util.as_local(starts_at)
# Exact match after rounding
if starts_at == target_time:

View file

@ -7,34 +7,28 @@ from dataclasses import dataclass
from datetime import timedelta
from typing import TYPE_CHECKING, Any
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator.time_service import TibberPricesTimeService
from custom_components.tibber_prices.const import (
BINARY_SENSOR_ICON_MAPPING,
MINUTES_PER_INTERVAL,
PRICE_LEVEL_CASH_ICON_MAPPING,
PRICE_LEVEL_ICON_MAPPING,
PRICE_RATING_ICON_MAPPING,
VOLATILITY_ICON_MAPPING,
)
from custom_components.tibber_prices.coordinator.helpers import get_intervals_for_day_offsets
from custom_components.tibber_prices.entity_utils.helpers import find_rolling_hour_center_index
from custom_components.tibber_prices.sensor.helpers import aggregate_level_data
from custom_components.tibber_prices.utils.price import find_price_data_for_interval
# Icon update logic uses timedelta directly (cosmetic, independent - allowed per AGENTS.md)
_INTERVAL_MINUTES = 15 # Tibber's 15-minute intervals
from homeassistant.util import dt as dt_util
@dataclass
class TibberPricesIconContext:
class IconContext:
"""Context data for dynamic icon selection."""
is_on: bool | None = None
coordinator_data: dict | None = None
has_future_periods_callback: Callable[[], bool] | None = None
period_is_active_callback: Callable[[], bool] | None = None
time: TibberPricesTimeService | None = None
if TYPE_CHECKING:
@ -54,7 +48,7 @@ def get_dynamic_icon(
key: str,
value: Any,
*,
context: TibberPricesIconContext | None = None,
context: IconContext | None = None,
) -> str | None:
"""
Get dynamic icon based on sensor state.
@ -70,13 +64,13 @@ def get_dynamic_icon(
Icon string or None if no dynamic icon applies
"""
ctx = context or TibberPricesIconContext()
ctx = context or IconContext()
# Try various icon sources in order
return (
get_trend_icon(key, value)
or get_timing_sensor_icon(key, value, period_is_active_callback=ctx.period_is_active_callback)
or get_price_sensor_icon(key, ctx.coordinator_data, time=ctx.time)
or get_price_sensor_icon(key, ctx.coordinator_data)
or get_level_sensor_icon(key, value)
or get_rating_sensor_icon(key, value)
or get_volatility_sensor_icon(key, value)
@ -85,25 +79,19 @@ def get_dynamic_icon(
def get_trend_icon(key: str, value: Any) -> str | None:
"""Get icon for trend sensors using 5-level trend scale."""
"""Get icon for trend sensors."""
# Handle next_price_trend_change TIMESTAMP sensor differently
# (icon based on attributes, not value which is a timestamp)
if key == "next_price_trend_change":
return None # Will be handled by sensor's icon property using attributes
if not key.startswith("price_trend_") and key != "current_price_trend":
if not key.startswith("price_trend_") or not isinstance(value, str):
return None
if not isinstance(value, str):
return None
# 5-level trend icons: strongly uses double arrows, normal uses single
trend_icons = {
"strongly_rising": "mdi:chevron-double-up", # Strong upward movement
"rising": "mdi:trending-up", # Normal upward trend
"stable": "mdi:trending-neutral", # No significant change
"falling": "mdi:trending-down", # Normal downward trend
"strongly_falling": "mdi:chevron-double-down", # Strong downward movement
"rising": "mdi:trending-up",
"falling": "mdi:trending-down",
"stable": "mdi:trending-neutral",
}
return trend_icons.get(value)
@ -176,12 +164,7 @@ def get_timing_sensor_icon(
return None
def get_price_sensor_icon(
key: str,
coordinator_data: dict | None,
*,
time: TibberPricesTimeService | None,
) -> str | None:
def get_price_sensor_icon(key: str, coordinator_data: dict | None) -> str | None:
"""
Get icon for current price sensors (dynamic based on price level).
@ -192,34 +175,32 @@ def get_price_sensor_icon(
Args:
key: Entity description key
coordinator_data: Coordinator data for price level lookups
time: TibberPricesTimeService instance (required for determining current interval)
Returns:
Icon string or None if not a current price sensor
"""
# Early exit if coordinator_data or time not available
if not coordinator_data or time is None:
if not coordinator_data:
return None
# Only current price sensors get dynamic icons
if key in ("current_interval_price", "current_interval_price_base"):
level = get_price_level_for_icon(coordinator_data, interval_offset=0, time=time)
if key == "current_interval_price":
level = get_price_level_for_icon(coordinator_data, interval_offset=0)
if level:
return PRICE_LEVEL_CASH_ICON_MAPPING.get(level.upper())
elif key == "next_interval_price":
# For next interval, use the next interval price level to determine icon
level = get_price_level_for_icon(coordinator_data, interval_offset=1, time=time)
level = get_price_level_for_icon(coordinator_data, interval_offset=1)
if level:
return PRICE_LEVEL_CASH_ICON_MAPPING.get(level.upper())
elif key == "current_hour_average_price":
# For current hour average, use the current hour price level to determine icon
level = get_rolling_hour_price_level_for_icon(coordinator_data, hour_offset=0, time=time)
level = get_rolling_hour_price_level_for_icon(coordinator_data, hour_offset=0)
if level:
return PRICE_LEVEL_CASH_ICON_MAPPING.get(level.upper())
elif key == "next_hour_average_price":
# For next hour average, use the next hour price level to determine icon
level = get_rolling_hour_price_level_for_icon(coordinator_data, hour_offset=1, time=time)
level = get_rolling_hour_price_level_for_icon(coordinator_data, hour_offset=1)
if level:
return PRICE_LEVEL_CASH_ICON_MAPPING.get(level.upper())
@ -307,7 +288,6 @@ def get_price_level_for_icon(
coordinator_data: dict,
*,
interval_offset: int | None = None,
time: TibberPricesTimeService,
) -> str | None:
"""
Get the price level for icon determination.
@ -317,7 +297,6 @@ def get_price_level_for_icon(
Args:
coordinator_data: Coordinator data
interval_offset: Interval offset (0=current, 1=next, -1=previous)
time: TibberPricesTimeService instance (required)
Returns:
Price level string or None if not found
@ -326,11 +305,12 @@ def get_price_level_for_icon(
if not coordinator_data or interval_offset is None:
return None
now = time.now()
price_info = coordinator_data.get("priceInfo", {})
now = dt_util.now()
# Interval-based lookup
target_time = now + timedelta(minutes=_INTERVAL_MINUTES * interval_offset)
interval_data = find_price_data_for_interval(coordinator_data, target_time, time=time)
target_time = now + timedelta(minutes=MINUTES_PER_INTERVAL * interval_offset)
interval_data = find_price_data_for_interval(price_info, target_time)
if not interval_data or "level" not in interval_data:
return None
@ -342,7 +322,6 @@ def get_rolling_hour_price_level_for_icon(
coordinator_data: dict,
*,
hour_offset: int = 0,
time: TibberPricesTimeService,
) -> str | None:
"""
Get the aggregated price level for rolling hour icon determination.
@ -355,7 +334,6 @@ def get_rolling_hour_price_level_for_icon(
Args:
coordinator_data: Coordinator data
hour_offset: Hour offset (0=current hour, 1=next hour)
time: TibberPricesTimeService instance (required)
Returns:
Aggregated price level string or None if not found
@ -364,15 +342,15 @@ def get_rolling_hour_price_level_for_icon(
if not coordinator_data:
return None
# Get all intervals (yesterday, today, tomorrow) via helper
all_prices = get_intervals_for_day_offsets(coordinator_data, [-1, 0, 1])
price_info = coordinator_data.get("priceInfo", {})
all_prices = price_info.get("yesterday", []) + price_info.get("today", []) + price_info.get("tomorrow", [])
if not all_prices:
return None
# Find center index using the same helper function as the sensor platform
now = time.now()
center_idx = find_rolling_hour_center_index(all_prices, now, hour_offset, time=time)
now = dt_util.now()
center_idx = find_rolling_hour_center_index(all_prices, now, hour_offset)
if center_idx is None:
return None

View file

@ -1,33 +0,0 @@
{
"services": {
"get_price": {
"service": "mdi:table-search"
},
"get_chartdata": {
"service": "mdi:chart-bar",
"sections": {
"general": "mdi:identifier",
"selection": "mdi:calendar-range",
"filters": "mdi:filter-variant",
"transformation": "mdi:tune",
"format": "mdi:file-table",
"arrays_of_objects": "mdi:code-json",
"arrays_of_arrays": "mdi:code-brackets"
}
},
"get_apexcharts_yaml": {
"service": "mdi:chart-line",
"sections": {
"entry_id": "mdi:identifier",
"day": "mdi:calendar-range",
"level_type": "mdi:format-list-bulleted-type",
"resolution": "mdi:timer-sand",
"highlight_best_price": "mdi:battery-charging-low",
"highlight_peak_price": "mdi:battery-alert"
}
},
"refresh_user_data": {
"service": "mdi:refresh"
}
}
}

View file

@ -1,21 +0,0 @@
"""Interval Pool - Intelligent interval caching and routing."""
from .manager import TibberPricesIntervalPool
from .routing import get_price_intervals_for_range
from .storage import (
INTERVAL_POOL_STORAGE_VERSION,
async_load_pool_state,
async_remove_pool_storage,
async_save_pool_state,
get_storage_key,
)
__all__ = [
"INTERVAL_POOL_STORAGE_VERSION",
"TibberPricesIntervalPool",
"async_load_pool_state",
"async_remove_pool_storage",
"async_save_pool_state",
"get_price_intervals_for_range",
"get_storage_key",
]

View file

@ -1,206 +0,0 @@
"""Fetch group cache for price intervals."""
from __future__ import annotations
import logging
from datetime import datetime, timedelta
from typing import TYPE_CHECKING, Any
from homeassistant.util import dt as dt_utils
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator.time_service import (
TibberPricesTimeService,
)
_LOGGER = logging.getLogger(__name__)
_LOGGER_DETAILS = logging.getLogger(__name__ + ".details")
# Protected date range: day-before-yesterday to tomorrow (4 days total)
PROTECTED_DAYS_BEFORE = 2 # day-before-yesterday + yesterday
PROTECTED_DAYS_AFTER = 1 # tomorrow
class TibberPricesIntervalPoolFetchGroupCache:
"""
Storage for fetch groups with protected range management.
A fetch group is a collection of intervals fetched at the same time,
stored together with their fetch timestamp for GC purposes.
Structure:
{
"fetched_at": datetime, # When this group was fetched
"intervals": [dict, ...] # List of interval dicts
}
Protected Range:
Intervals within day-before-yesterday to tomorrow are protected
and never evicted from cache. This range shifts daily automatically.
Example (today = 2025-11-25):
Protected: 2025-11-23 00:00 to 2025-11-27 00:00
"""
def __init__(self, *, time_service: TibberPricesTimeService | None = None) -> None:
"""Initialize empty fetch group cache with optional TimeService."""
self._fetch_groups: list[dict[str, Any]] = []
self._time_service = time_service
# Protected range cache (invalidated daily)
self._protected_range_cache: tuple[str, str] | None = None
self._protected_range_cache_date: str | None = None
def add_fetch_group(
self,
intervals: list[dict[str, Any]],
fetched_at: datetime,
) -> int:
"""
Add new fetch group to cache.
Args:
intervals: List of interval dicts (sorted by startsAt).
fetched_at: Timestamp when intervals were fetched.
Returns:
Index of the newly added fetch group.
"""
fetch_group = {
"fetched_at": fetched_at,
"intervals": intervals,
}
fetch_group_index = len(self._fetch_groups)
self._fetch_groups.append(fetch_group)
_LOGGER_DETAILS.debug(
"Added fetch group %d: %d intervals (fetched at %s)",
fetch_group_index,
len(intervals),
fetched_at.isoformat(),
)
return fetch_group_index
def get_fetch_groups(self) -> list[dict[str, Any]]:
"""Get all fetch groups (read-only access)."""
return self._fetch_groups
def set_fetch_groups(self, fetch_groups: list[dict[str, Any]]) -> None:
"""Replace all fetch groups (used during GC)."""
self._fetch_groups = fetch_groups
def get_protected_range(self) -> tuple[str, str]:
"""
Get protected date range as ISO strings.
Protected range: day-before-yesterday 00:00 to day-after-tomorrow 00:00.
This range shifts daily automatically.
Time Machine Support:
If time_service was provided at init, uses time_service.now() for
"today" calculation. This protects the correct date range when
simulating a different date.
Returns:
Tuple of (start_iso, end_iso) for protected range.
Start is inclusive, end is exclusive.
Example (today = 2025-11-25):
Returns: ("2025-11-23T00:00:00+01:00", "2025-11-27T00:00:00+01:00")
Protected days: 2025-11-23, 2025-11-24, 2025-11-25, 2025-11-26
"""
# Use TimeService if available (Time Machine support), else real time
now = self._time_service.now() if self._time_service else dt_utils.now()
today_date_str = now.date().isoformat()
# Check cache validity (invalidate daily)
if self._protected_range_cache_date == today_date_str and self._protected_range_cache:
return self._protected_range_cache
# Calculate new protected range
today_midnight = now.replace(hour=0, minute=0, second=0, microsecond=0)
# Start: day-before-yesterday at 00:00
start_dt = today_midnight - timedelta(days=PROTECTED_DAYS_BEFORE)
# End: day after tomorrow at 00:00 (exclusive, so tomorrow is included)
end_dt = today_midnight + timedelta(days=PROTECTED_DAYS_AFTER + 1)
# Convert to ISO strings and cache
start_iso = start_dt.isoformat()
end_iso = end_dt.isoformat()
self._protected_range_cache = (start_iso, end_iso)
self._protected_range_cache_date = today_date_str
return start_iso, end_iso
def is_interval_protected(self, interval: dict[str, Any]) -> bool:
"""
Check if interval is within protected date range.
Protected intervals are never evicted from cache.
Args:
interval: Interval dict with "startsAt" ISO timestamp.
Returns:
True if interval is protected (within protected range).
"""
starts_at_iso = interval["startsAt"]
start_protected_iso, end_protected_iso = self.get_protected_range()
# Fast string comparison (ISO timestamps are lexicographically sortable)
return start_protected_iso <= starts_at_iso < end_protected_iso
def count_total_intervals(self) -> int:
"""Count total intervals across all fetch groups."""
return sum(len(group["intervals"]) for group in self._fetch_groups)
def to_dict(self) -> dict[str, Any]:
"""
Serialize fetch groups for storage.
Returns:
Dict with serializable fetch groups.
"""
return {
"fetch_groups": [
{
"fetched_at": group["fetched_at"].isoformat(),
"intervals": group["intervals"],
}
for group in self._fetch_groups
],
}
@classmethod
def from_dict(cls, data: dict[str, Any]) -> TibberPricesIntervalPoolFetchGroupCache:
"""
Restore fetch groups from storage.
Args:
data: Dict with "fetch_groups" list.
Returns:
TibberPricesIntervalPoolFetchGroupCache instance with restored data.
"""
cache = cls()
fetch_groups_data = data.get("fetch_groups", [])
cache._fetch_groups = [
{
"fetched_at": datetime.fromisoformat(group["fetched_at"]),
"intervals": group["intervals"],
}
for group in fetch_groups_data
]
return cache

View file

@ -1,321 +0,0 @@
"""Interval fetcher - coverage check and API coordination for interval pool."""
from __future__ import annotations
import logging
from datetime import UTC, datetime, timedelta
from typing import TYPE_CHECKING, Any
from homeassistant.util import dt as dt_utils
if TYPE_CHECKING:
from collections.abc import Callable
from custom_components.tibber_prices.api import TibberPricesApiClient
from .cache import TibberPricesIntervalPoolFetchGroupCache
from .index import TibberPricesIntervalPoolTimestampIndex
_LOGGER = logging.getLogger(__name__)
_LOGGER_DETAILS = logging.getLogger(__name__ + ".details")
# Resolution change date (hourly before, quarter-hourly after)
# Use UTC for constant - timezone adjusted at runtime when comparing
RESOLUTION_CHANGE_DATETIME = datetime(2025, 10, 1, tzinfo=UTC)
RESOLUTION_CHANGE_ISO = "2025-10-01T00:00:00"
# Interval lengths in minutes
INTERVAL_HOURLY = 60
INTERVAL_QUARTER_HOURLY = 15
# Minimum gap sizes in seconds
MIN_GAP_HOURLY = 3600 # 1 hour
MIN_GAP_QUARTER_HOURLY = 900 # 15 minutes
# Tolerance for time comparisons (±1 second for floating point/timezone issues)
TIME_TOLERANCE_SECONDS = 1
TIME_TOLERANCE_MINUTES = 1
class TibberPricesIntervalPoolFetcher:
"""Fetch missing intervals from API based on coverage check."""
def __init__(
self,
api: TibberPricesApiClient,
cache: TibberPricesIntervalPoolFetchGroupCache,
index: TibberPricesIntervalPoolTimestampIndex,
home_id: str,
) -> None:
"""
Initialize fetcher.
Args:
api: API client for Tibber GraphQL queries.
cache: Fetch group cache for storage operations.
index: Timestamp index for gap detection.
home_id: Tibber home ID for API calls.
"""
self._api = api
self._cache = cache
self._index = index
self._home_id = home_id
def check_coverage(
self,
cached_intervals: list[dict[str, Any]],
start_time_iso: str,
end_time_iso: str,
) -> list[tuple[str, str]]:
"""
Check cache coverage and find missing time ranges.
This method minimizes API calls by:
1. Finding all gaps in cached intervals
2. Treating each cached interval as a discrete timestamp
3. Gaps are time ranges between consecutive cached timestamps
Handles both resolutions:
- Pre-2025-10-01: Hourly intervals (:00:00 only)
- Post-2025-10-01: Quarter-hourly intervals (:00:00, :15:00, :30:00, :45:00)
- DST transitions (23h/25h days)
The API requires an interval count (first: X parameter).
For historical data (pre-2025-10-01), Tibber only stored hourly prices.
The API returns whatever intervals exist for the requested period.
Args:
cached_intervals: List of cached intervals (may be empty).
start_time_iso: ISO timestamp string (inclusive).
end_time_iso: ISO timestamp string (exclusive).
Returns:
List of (start_iso, end_iso) tuples representing missing ranges.
Each tuple represents a continuous time span that needs fetching.
Ranges are automatically split at resolution change boundary.
Example:
Requested: 2025-11-13T00:00:00 to 2025-11-13T02:00:00
Cached: [00:00, 00:15, 01:30, 01:45]
Gaps: [(00:15, 01:30)] - missing intervals between groups
"""
if not cached_intervals:
# No cache → fetch entire range
return [(start_time_iso, end_time_iso)]
# Filter and sort cached intervals within requested range
in_range_intervals = [
interval for interval in cached_intervals if start_time_iso <= interval["startsAt"] < end_time_iso
]
sorted_intervals = sorted(in_range_intervals, key=lambda x: x["startsAt"])
if not sorted_intervals:
# All cached intervals are outside requested range
return [(start_time_iso, end_time_iso)]
missing_ranges = []
# Parse start/end times once
start_time_dt = datetime.fromisoformat(start_time_iso)
end_time_dt = datetime.fromisoformat(end_time_iso)
# Get first cached interval datetime for resolution logic
first_cached_dt = datetime.fromisoformat(sorted_intervals[0]["startsAt"])
resolution_change_dt = RESOLUTION_CHANGE_DATETIME.replace(tzinfo=first_cached_dt.tzinfo)
# Check gap before first cached interval
time_diff_before_first = (first_cached_dt - start_time_dt).total_seconds()
if time_diff_before_first > TIME_TOLERANCE_SECONDS:
missing_ranges.append((start_time_iso, sorted_intervals[0]["startsAt"]))
_LOGGER_DETAILS.debug(
"Missing range before first cached interval: %s to %s (%.1f seconds)",
start_time_iso,
sorted_intervals[0]["startsAt"],
time_diff_before_first,
)
# Check gaps between consecutive cached intervals
for i in range(len(sorted_intervals) - 1):
current_interval = sorted_intervals[i]
next_interval = sorted_intervals[i + 1]
current_start = current_interval["startsAt"]
next_start = next_interval["startsAt"]
# Parse to datetime for accurate time difference
current_dt = datetime.fromisoformat(current_start)
next_dt = datetime.fromisoformat(next_start)
# Calculate time difference in minutes
time_diff_minutes = (next_dt - current_dt).total_seconds() / 60
# Determine expected interval length based on date
expected_interval_minutes = (
INTERVAL_HOURLY if current_dt < resolution_change_dt else INTERVAL_QUARTER_HOURLY
)
# Only create gap if intervals are NOT consecutive
if time_diff_minutes > expected_interval_minutes + TIME_TOLERANCE_MINUTES:
# Gap exists - missing intervals between them
# Missing range starts AFTER current interval ends
current_interval_end = current_dt + timedelta(minutes=expected_interval_minutes)
missing_ranges.append((current_interval_end.isoformat(), next_start))
_LOGGER_DETAILS.debug(
"Missing range between cached intervals: %s (ends at %s) to %s (%.1f min, expected %d min)",
current_start,
current_interval_end.isoformat(),
next_start,
time_diff_minutes,
expected_interval_minutes,
)
# Check gap after last cached interval
# An interval's startsAt time represents the START of that interval.
# The interval covers [startsAt, startsAt + interval_length).
# So the last interval ENDS at (startsAt + interval_length), not at startsAt!
last_cached_dt = datetime.fromisoformat(sorted_intervals[-1]["startsAt"])
# Calculate when the last interval ENDS
interval_minutes = INTERVAL_QUARTER_HOURLY if last_cached_dt >= resolution_change_dt else INTERVAL_HOURLY
last_interval_end_dt = last_cached_dt + timedelta(minutes=interval_minutes)
# Only create gap if there's uncovered time AFTER the last interval ends
time_diff_after_last = (end_time_dt - last_interval_end_dt).total_seconds()
# Need at least one full interval of gap
min_gap_seconds = MIN_GAP_QUARTER_HOURLY if last_cached_dt >= resolution_change_dt else MIN_GAP_HOURLY
if time_diff_after_last >= min_gap_seconds:
# Missing range starts AFTER the last cached interval ends
missing_ranges.append((last_interval_end_dt.isoformat(), end_time_iso))
_LOGGER_DETAILS.debug(
"Missing range after last cached interval: %s (ends at %s) to %s (%.1f seconds, need >= %d)",
sorted_intervals[-1]["startsAt"],
last_interval_end_dt.isoformat(),
end_time_iso,
time_diff_after_last,
min_gap_seconds,
)
if not missing_ranges:
_LOGGER.debug(
"Full coverage - all intervals cached for range %s to %s",
start_time_iso,
end_time_iso,
)
return missing_ranges
# Split ranges at resolution change boundary (2025-10-01 00:00:00)
# This simplifies interval count calculation in API calls:
# - Pre-2025-10-01: Always hourly (1 interval/hour)
# - Post-2025-10-01: Always quarter-hourly (4 intervals/hour)
return self._split_at_resolution_boundary(missing_ranges)
def _split_at_resolution_boundary(self, ranges: list[tuple[str, str]]) -> list[tuple[str, str]]:
"""
Split time ranges at resolution change boundary.
Args:
ranges: List of (start_iso, end_iso) tuples.
Returns:
List of ranges split at 2025-10-01T00:00:00 boundary.
"""
split_ranges = []
for start_iso, end_iso in ranges:
# Check if range crosses the boundary
if start_iso < RESOLUTION_CHANGE_ISO < end_iso:
# Split into two ranges: before and after boundary
split_ranges.append((start_iso, RESOLUTION_CHANGE_ISO))
split_ranges.append((RESOLUTION_CHANGE_ISO, end_iso))
_LOGGER_DETAILS.debug(
"Split range at resolution boundary: (%s, %s) → (%s, %s) + (%s, %s)",
start_iso,
end_iso,
start_iso,
RESOLUTION_CHANGE_ISO,
RESOLUTION_CHANGE_ISO,
end_iso,
)
else:
# Range doesn't cross boundary - keep as is
split_ranges.append((start_iso, end_iso))
return split_ranges
async def fetch_missing_ranges(
self,
api_client: TibberPricesApiClient,
user_data: dict[str, Any],
missing_ranges: list[tuple[str, str]],
*,
on_intervals_fetched: Callable[[list[dict[str, Any]], str], None] | None = None,
) -> list[list[dict[str, Any]]]:
"""
Fetch missing intervals from API.
Makes one API call per missing range. Uses routing logic to select
the optimal endpoint (PRICE_INFO vs PRICE_INFO_RANGE).
Args:
api_client: TibberPricesApiClient instance for API calls.
user_data: User data dict containing home metadata.
missing_ranges: List of (start_iso, end_iso) tuples to fetch.
on_intervals_fetched: Optional callback for each fetch result.
Receives (intervals, fetch_time_iso).
Returns:
List of interval lists (one per missing range).
Each sublist contains intervals from one API call.
Raises:
TibberPricesApiClientError: If API calls fail.
"""
# Import here to avoid circular dependency
from custom_components.tibber_prices.interval_pool.routing import ( # noqa: PLC0415
get_price_intervals_for_range,
)
fetch_time_iso = dt_utils.now().isoformat()
all_fetched_intervals = []
for idx, (missing_start_iso, missing_end_iso) in enumerate(missing_ranges, start=1):
_LOGGER_DETAILS.debug(
"Fetching from Tibber API (%d/%d) for home %s: range %s to %s",
idx,
len(missing_ranges),
self._home_id,
missing_start_iso,
missing_end_iso,
)
# Parse ISO strings back to datetime for API call
missing_start_dt = datetime.fromisoformat(missing_start_iso)
missing_end_dt = datetime.fromisoformat(missing_end_iso)
# Fetch intervals from API - routing returns ALL intervals (unfiltered)
fetched_intervals = await get_price_intervals_for_range(
api_client=api_client,
home_id=self._home_id,
user_data=user_data,
start_time=missing_start_dt,
end_time=missing_end_dt,
)
all_fetched_intervals.append(fetched_intervals)
_LOGGER_DETAILS.debug(
"Received %d intervals from Tibber API for home %s",
len(fetched_intervals),
self._home_id,
)
# Notify callback if provided (for immediate caching)
if on_intervals_fetched:
on_intervals_fetched(fetched_intervals, fetch_time_iso)
return all_fetched_intervals

View file

@ -1,283 +0,0 @@
"""Garbage collector for interval cache eviction."""
from __future__ import annotations
import logging
from datetime import datetime
from typing import TYPE_CHECKING, Any
if TYPE_CHECKING:
from .cache import TibberPricesIntervalPoolFetchGroupCache
from .index import TibberPricesIntervalPoolTimestampIndex
_LOGGER = logging.getLogger(__name__)
_LOGGER_DETAILS = logging.getLogger(__name__ + ".details")
# Maximum number of intervals to cache
# 1 days @ 15min resolution = 10 * 96 = 960 intervals
MAX_CACHE_SIZE = 960
def _normalize_starts_at(starts_at: datetime | str) -> str:
"""Normalize startsAt to consistent format (YYYY-MM-DDTHH:MM:SS)."""
if isinstance(starts_at, datetime):
return starts_at.strftime("%Y-%m-%dT%H:%M:%S")
return starts_at[:19]
class TibberPricesIntervalPoolGarbageCollector:
"""
Manages cache eviction and dead interval cleanup.
Eviction Strategy:
- Evict oldest fetch groups first (by fetched_at timestamp)
- Protected intervals (day-before-yesterday to tomorrow) are NEVER evicted
- Evict complete fetch groups, not individual intervals
Dead Interval Cleanup:
When intervals are "touched" (re-fetched), they move to a new fetch group
but remain in the old group. This creates "dead intervals" that occupy
memory but are no longer referenced by the index.
"""
def __init__(
self,
cache: TibberPricesIntervalPoolFetchGroupCache,
index: TibberPricesIntervalPoolTimestampIndex,
home_id: str,
) -> None:
"""
Initialize garbage collector.
Args:
home_id: Home ID for logging purposes.
cache: Fetch group cache to manage.
index: Timestamp index for living interval detection.
"""
self._home_id = home_id
self._cache = cache
self._index = index
def run_gc(self) -> bool:
"""
Run garbage collection if needed.
Process:
1. Clean up dead intervals from all fetch groups
2. Count total intervals
3. If > MAX_CACHE_SIZE, evict oldest fetch groups
4. Rebuild index after eviction
Returns:
True if any cleanup or eviction happened, False otherwise.
"""
fetch_groups = self._cache.get_fetch_groups()
# Phase 1: Clean up dead intervals
dead_count = self._cleanup_dead_intervals(fetch_groups)
if dead_count > 0:
_LOGGER_DETAILS.debug(
"GC cleaned %d dead intervals (home %s)",
dead_count,
self._home_id,
)
# Phase 1.5: Remove empty fetch groups (after dead interval cleanup)
empty_removed = self._remove_empty_groups(fetch_groups)
if empty_removed > 0:
_LOGGER_DETAILS.debug(
"GC removed %d empty fetch groups (home %s)",
empty_removed,
self._home_id,
)
# Phase 2: Count total intervals after cleanup
total_intervals = self._cache.count_total_intervals()
if total_intervals <= MAX_CACHE_SIZE:
_LOGGER_DETAILS.debug(
"GC cleanup only for home %s: %d intervals <= %d limit (no eviction needed)",
self._home_id,
total_intervals,
MAX_CACHE_SIZE,
)
return dead_count > 0
# Phase 3: Evict old fetch groups
evicted_indices = self._evict_old_groups(fetch_groups, total_intervals)
if not evicted_indices:
# All intervals are protected, cannot evict
return dead_count > 0 or empty_removed > 0
# Phase 4: Rebuild cache and index
new_fetch_groups = [group for idx, group in enumerate(fetch_groups) if idx not in evicted_indices]
self._cache.set_fetch_groups(new_fetch_groups)
self._index.rebuild(new_fetch_groups)
_LOGGER_DETAILS.debug(
"GC evicted %d fetch groups (home %s): %d intervals remaining",
len(evicted_indices),
self._home_id,
self._cache.count_total_intervals(),
)
return True
def _remove_empty_groups(self, fetch_groups: list[dict[str, Any]]) -> int:
"""
Remove fetch groups with no intervals.
After dead interval cleanup, some groups may be completely empty.
These should be removed to prevent memory accumulation.
Note: This modifies the cache's internal list in-place and rebuilds
the index to maintain consistency.
Args:
fetch_groups: List of fetch groups (will be modified).
Returns:
Number of empty groups removed.
"""
# Find non-empty groups
non_empty_groups = [group for group in fetch_groups if group["intervals"]]
removed_count = len(fetch_groups) - len(non_empty_groups)
if removed_count > 0:
# Update cache with filtered list
self._cache.set_fetch_groups(non_empty_groups)
# Rebuild index since group indices changed
self._index.rebuild(non_empty_groups)
return removed_count
def _cleanup_dead_intervals(self, fetch_groups: list[dict[str, Any]]) -> int:
"""
Remove dead intervals from all fetch groups.
Dead intervals are no longer referenced by the index (they were touched
and moved to a newer fetch group).
Args:
fetch_groups: List of fetch groups to clean.
Returns:
Total number of dead intervals removed.
"""
total_dead = 0
for group_idx, group in enumerate(fetch_groups):
old_intervals = group["intervals"]
if not old_intervals:
continue
# Find living intervals (still in index at correct position)
living_intervals = []
for interval_idx, interval in enumerate(old_intervals):
starts_at_normalized = _normalize_starts_at(interval["startsAt"])
index_entry = self._index.get(starts_at_normalized)
if index_entry is not None:
# Check if index points to THIS position
if index_entry["fetch_group_index"] == group_idx and index_entry["interval_index"] == interval_idx:
living_intervals.append(interval)
else:
# Dead: index points elsewhere
total_dead += 1
else:
# Dead: not in index
total_dead += 1
# Replace with cleaned list if any dead intervals found
if len(living_intervals) < len(old_intervals):
group["intervals"] = living_intervals
dead_count = len(old_intervals) - len(living_intervals)
_LOGGER_DETAILS.debug(
"GC cleaned %d dead intervals from fetch group %d (home %s)",
dead_count,
group_idx,
self._home_id,
)
return total_dead
def _evict_old_groups(
self,
fetch_groups: list[dict[str, Any]],
total_intervals: int,
) -> set[int]:
"""
Determine which fetch groups to evict to stay under MAX_CACHE_SIZE.
Only evicts groups without protected intervals.
Groups evicted oldest-first (by fetched_at).
Args:
fetch_groups: List of fetch groups.
total_intervals: Total interval count.
Returns:
Set of fetch group indices to evict.
"""
start_protected_iso, end_protected_iso = self._cache.get_protected_range()
_LOGGER_DETAILS.debug(
"Protected range: %s to %s",
start_protected_iso[:10],
end_protected_iso[:10],
)
# Classify: protected vs evictable
evictable_groups = []
for idx, group in enumerate(fetch_groups):
has_protected = any(self._cache.is_interval_protected(interval) for interval in group["intervals"])
if not has_protected:
evictable_groups.append((idx, group))
# Sort by fetched_at (oldest first)
evictable_groups.sort(key=lambda x: x[1]["fetched_at"])
_LOGGER_DETAILS.debug(
"GC: %d protected groups, %d evictable groups",
len(fetch_groups) - len(evictable_groups),
len(evictable_groups),
)
# Evict until under limit
evicted_indices = set()
remaining = total_intervals
for idx, group in evictable_groups:
if remaining <= MAX_CACHE_SIZE:
break
group_count = len(group["intervals"])
evicted_indices.add(idx)
remaining -= group_count
_LOGGER_DETAILS.debug(
"GC evicting group %d (fetched %s): %d intervals, %d remaining",
idx,
group["fetched_at"].isoformat(),
group_count,
remaining,
)
if not evicted_indices:
_LOGGER.warning(
"GC cannot evict any groups (home %s): all %d intervals are protected",
self._home_id,
total_intervals,
)
return evicted_indices

View file

@ -1,173 +0,0 @@
"""Timestamp index for O(1) interval lookups."""
from __future__ import annotations
import logging
from typing import Any
_LOGGER = logging.getLogger(__name__)
_LOGGER_DETAILS = logging.getLogger(__name__ + ".details")
class TibberPricesIntervalPoolTimestampIndex:
"""
Fast O(1) timestamp-based interval lookup.
Maps normalized ISO timestamp strings to fetch group + interval indices.
Structure:
{
"2025-11-25T00:00:00": {
"fetch_group_index": 0, # Index in fetch groups list
"interval_index": 2 # Index within that group's intervals
},
...
}
Normalization:
Timestamps are normalized to 19 characters (YYYY-MM-DDTHH:MM:SS)
by truncating microseconds and timezone info for fast string comparison.
"""
def __init__(self) -> None:
"""Initialize empty timestamp index."""
self._index: dict[str, dict[str, int]] = {}
def add(
self,
interval: dict[str, Any],
fetch_group_index: int,
interval_index: int,
) -> None:
"""
Add interval to index.
Args:
interval: Interval dict with "startsAt" ISO timestamp.
fetch_group_index: Index of fetch group containing this interval.
interval_index: Index within that fetch group's intervals list.
"""
starts_at_normalized = self._normalize_timestamp(interval["startsAt"])
self._index[starts_at_normalized] = {
"fetch_group_index": fetch_group_index,
"interval_index": interval_index,
}
def get(self, timestamp: str) -> dict[str, int] | None:
"""
Look up interval location by timestamp.
Args:
timestamp: ISO timestamp string (will be normalized).
Returns:
Dict with fetch_group_index and interval_index, or None if not found.
"""
starts_at_normalized = self._normalize_timestamp(timestamp)
return self._index.get(starts_at_normalized)
def contains(self, timestamp: str) -> bool:
"""
Check if timestamp exists in index.
Args:
timestamp: ISO timestamp string (will be normalized).
Returns:
True if timestamp is in index.
"""
starts_at_normalized = self._normalize_timestamp(timestamp)
return starts_at_normalized in self._index
def remove(self, timestamp: str) -> None:
"""
Remove timestamp from index.
Args:
timestamp: ISO timestamp string (will be normalized).
"""
starts_at_normalized = self._normalize_timestamp(timestamp)
self._index.pop(starts_at_normalized, None)
def update_batch(
self,
updates: list[tuple[str, int, int]],
) -> None:
"""
Update multiple index entries efficiently in a single operation.
More efficient than calling remove() + add() for each entry,
as it avoids repeated dict operations and normalization.
Args:
updates: List of (timestamp, fetch_group_index, interval_index) tuples.
Timestamps will be normalized automatically.
"""
for timestamp, fetch_group_index, interval_index in updates:
starts_at_normalized = self._normalize_timestamp(timestamp)
self._index[starts_at_normalized] = {
"fetch_group_index": fetch_group_index,
"interval_index": interval_index,
}
def clear(self) -> None:
"""Clear entire index."""
self._index.clear()
def rebuild(self, fetch_groups: list[dict[str, Any]]) -> None:
"""
Rebuild index from fetch groups.
Used after GC operations that modify fetch group structure.
Args:
fetch_groups: List of fetch group dicts.
"""
self._index.clear()
for fetch_group_idx, group in enumerate(fetch_groups):
for interval_idx, interval in enumerate(group["intervals"]):
starts_at_normalized = self._normalize_timestamp(interval["startsAt"])
self._index[starts_at_normalized] = {
"fetch_group_index": fetch_group_idx,
"interval_index": interval_idx,
}
_LOGGER_DETAILS.debug(
"Rebuilt index: %d timestamps indexed",
len(self._index),
)
def get_raw_index(self) -> dict[str, dict[str, int]]:
"""Get raw index dict (for serialization)."""
return self._index
def count(self) -> int:
"""Count total indexed timestamps."""
return len(self._index)
@staticmethod
def _normalize_timestamp(timestamp: str) -> str:
"""
Normalize ISO timestamp for indexing.
Truncates to 19 characters (YYYY-MM-DDTHH:MM:SS) to remove
microseconds and timezone info for consistent string comparison.
Args:
timestamp: Full ISO timestamp string.
Returns:
Normalized timestamp (19 chars).
Example:
"2025-11-25T00:00:00.000+01:00" "2025-11-25T00:00:00"
"""
return timestamp[:19]

View file

@ -1,830 +0,0 @@
"""Interval pool manager - main coordinator for interval caching."""
from __future__ import annotations
import asyncio
import contextlib
import logging
from datetime import datetime, timedelta
from typing import TYPE_CHECKING, Any
from zoneinfo import ZoneInfo
from custom_components.tibber_prices.api.exceptions import TibberPricesApiClientError
from homeassistant.util import dt as dt_utils
from .cache import TibberPricesIntervalPoolFetchGroupCache
from .fetcher import TibberPricesIntervalPoolFetcher
from .garbage_collector import MAX_CACHE_SIZE, TibberPricesIntervalPoolGarbageCollector
from .index import TibberPricesIntervalPoolTimestampIndex
from .storage import async_save_pool_state
if TYPE_CHECKING:
from custom_components.tibber_prices.api.client import TibberPricesApiClient
from custom_components.tibber_prices.coordinator.time_service import (
TibberPricesTimeService,
)
_LOGGER = logging.getLogger(__name__)
_LOGGER_DETAILS = logging.getLogger(__name__ + ".details")
# Interval lengths in minutes
INTERVAL_HOURLY = 60
INTERVAL_QUARTER_HOURLY = 15
# Debounce delay for auto-save (seconds)
DEBOUNCE_DELAY_SECONDS = 3.0
def _normalize_starts_at(starts_at: datetime | str) -> str:
"""Normalize startsAt to consistent format (YYYY-MM-DDTHH:MM:SS)."""
if isinstance(starts_at, datetime):
return starts_at.strftime("%Y-%m-%dT%H:%M:%S")
return starts_at[:19]
class TibberPricesIntervalPool:
"""
High-performance interval cache manager for a single Tibber home.
Coordinates all interval pool components:
- TibberPricesIntervalPoolFetchGroupCache: Stores fetch groups and manages protected ranges
- TibberPricesIntervalPoolTimestampIndex: Provides O(1) timestamp lookups
- TibberPricesIntervalPoolGarbageCollector: Evicts old fetch groups when cache exceeds limits
- TibberPricesIntervalPoolFetcher: Detects gaps and fetches missing intervals from API
Architecture:
- Each manager handles exactly ONE home (1:1 with config entry)
- home_id is immutable after initialization
- All operations are thread-safe via asyncio locks
Features:
- Fetch-time based eviction (oldest fetch groups removed first)
- Protected date range (day-before-yesterday to tomorrow never evicted)
- Fast O(1) lookups by timestamp
- Automatic gap detection and API fetching
- Debounced auto-save to prevent excessive I/O
Example:
manager = TibberPricesIntervalPool(home_id="abc123", hass=hass, entry_id=entry.entry_id)
intervals = await manager.get_intervals(
api_client=client,
user_data=data,
start_time=datetime(...),
end_time=datetime(...),
)
"""
def __init__(
self,
*,
home_id: str,
api: TibberPricesApiClient,
hass: Any | None = None,
entry_id: str | None = None,
time_service: TibberPricesTimeService | None = None,
) -> None:
"""
Initialize interval pool manager.
Args:
home_id: Tibber home ID (required, immutable).
api: API client for fetching intervals.
hass: HomeAssistant instance for auto-save (optional).
entry_id: Config entry ID for auto-save (optional).
time_service: TimeService for time-travel support (optional).
If None, uses real time (dt_utils.now()).
"""
self._home_id = home_id
self._time_service = time_service
# Initialize components with dependency injection
self._cache = TibberPricesIntervalPoolFetchGroupCache(time_service=time_service)
self._index = TibberPricesIntervalPoolTimestampIndex()
self._gc = TibberPricesIntervalPoolGarbageCollector(self._cache, self._index, home_id)
self._fetcher = TibberPricesIntervalPoolFetcher(api, self._cache, self._index, home_id)
# Auto-save support
self._hass = hass
self._entry_id = entry_id
self._background_tasks: set[asyncio.Task] = set()
self._save_debounce_task: asyncio.Task | None = None
self._save_lock = asyncio.Lock()
async def get_intervals(
self,
api_client: TibberPricesApiClient,
user_data: dict[str, Any],
start_time: datetime,
end_time: datetime,
) -> tuple[list[dict[str, Any]], bool]:
"""
Get price intervals for time range (cached + fetch missing).
Main entry point for retrieving intervals. Coordinates:
1. Check cache for existing intervals
2. Detect missing time ranges
3. Fetch missing ranges from API
4. Add new intervals to cache (may trigger GC)
5. Return complete interval list
User receives ALL requested intervals even if cache exceeds limits.
Cache only keeps the most recent intervals (FIFO eviction).
Args:
api_client: TibberPricesApiClient instance for API calls.
user_data: User data dict containing home metadata.
start_time: Start of range (inclusive, timezone-aware).
end_time: End of range (exclusive, timezone-aware).
Returns:
Tuple of (intervals, api_called):
- intervals: List of price interval dicts, sorted by startsAt.
Contains ALL intervals in requested range (cached + fetched).
- api_called: True if API was called to fetch missing data, False if all from cache.
Raises:
TibberPricesApiClientError: If API calls fail or validation errors.
"""
# Validate inputs
if not user_data:
msg = "User data required for timezone-aware price fetching"
raise TibberPricesApiClientError(msg)
if start_time >= end_time:
msg = f"Invalid time range: start_time ({start_time}) must be before end_time ({end_time})"
raise TibberPricesApiClientError(msg)
# Convert to ISO strings for cache operations
start_time_iso = start_time.isoformat()
end_time_iso = end_time.isoformat()
_LOGGER_DETAILS.debug(
"Interval pool request for home %s: range %s to %s",
self._home_id,
start_time_iso,
end_time_iso,
)
# Get cached intervals using index
cached_intervals = self._get_cached_intervals(start_time_iso, end_time_iso)
# Check coverage - find ranges not in cache
missing_ranges = self._fetcher.check_coverage(cached_intervals, start_time_iso, end_time_iso)
if missing_ranges:
_LOGGER_DETAILS.debug(
"Coverage check for home %s: %d range(s) missing - will fetch from API",
self._home_id,
len(missing_ranges),
)
else:
_LOGGER_DETAILS.debug(
"Coverage check for home %s: full coverage in cache - no API calls needed",
self._home_id,
)
# Fetch missing ranges from API
if missing_ranges:
fetch_time_iso = dt_utils.now().isoformat()
# Fetch with callback for immediate caching
await self._fetcher.fetch_missing_ranges(
api_client=api_client,
user_data=user_data,
missing_ranges=missing_ranges,
on_intervals_fetched=lambda intervals, _: self._add_intervals(intervals, fetch_time_iso),
)
# After caching all API responses, read from cache again to get final result
# This ensures we return exactly what user requested, filtering out extra intervals
final_result = self._get_cached_intervals(start_time_iso, end_time_iso)
# Track if API was called (True if any missing ranges were fetched)
api_called = len(missing_ranges) > 0
_LOGGER_DETAILS.debug(
"Pool returning %d intervals for home %s (from cache: %d, fetched from API: %d ranges, api_called=%s)",
len(final_result),
self._home_id,
len(cached_intervals),
len(missing_ranges),
api_called,
)
return final_result, api_called
async def get_sensor_data(
self,
api_client: TibberPricesApiClient,
user_data: dict[str, Any],
home_timezone: str | None = None,
*,
include_tomorrow: bool = True,
) -> tuple[list[dict[str, Any]], bool]:
"""
Get price intervals for sensor data (day-before-yesterday to end-of-tomorrow).
Convenience method for coordinator/sensors that need the standard 4-day window:
- Day before yesterday (for trailing 24h averages at midnight)
- Yesterday (for trailing 24h averages)
- Today (current prices)
- Tomorrow (if available in cache)
IMPORTANT - Two distinct behaviors:
1. API FETCH: Controlled by include_tomorrow flag
- include_tomorrow=False Only fetch up to end of today (prevents API spam before 13:00)
- include_tomorrow=True Fetch including tomorrow data
2. RETURN DATA: Always returns full protected range (including tomorrow if cached)
- This ensures cached tomorrow data is used even if include_tomorrow=False
The separation prevents the following bug:
- If include_tomorrow affected both fetch AND return, cached tomorrow data
would be lost when include_tomorrow=False, causing infinite refresh loops.
Args:
api_client: TibberPricesApiClient instance for API calls.
user_data: User data dict containing home metadata.
home_timezone: Optional timezone string (e.g., "Europe/Berlin").
include_tomorrow: If True, fetch tomorrow's data from API. If False,
only fetch up to end of today. Default True.
DOES NOT affect returned data - always returns full range.
Returns:
Tuple of (intervals, api_called):
- intervals: List of price interval dicts for the 4-day window (including any cached
tomorrow data), sorted by startsAt.
- api_called: True if API was called to fetch missing data, False if all from cache.
"""
# Determine timezone
tz_str = home_timezone
if not tz_str:
tz_str = self._extract_timezone_from_user_data(user_data)
# Calculate range in home's timezone
tz = ZoneInfo(tz_str) if tz_str else None
now = self._time_service.now() if self._time_service else dt_utils.now()
now_local = now.astimezone(tz) if tz else now
# Day before yesterday 00:00 (start) - same for both fetch and return
day_before_yesterday = (now_local - timedelta(days=2)).replace(hour=0, minute=0, second=0, microsecond=0)
# End of tomorrow (full protected range) - used for RETURN data
end_of_tomorrow = (now_local + timedelta(days=2)).replace(hour=0, minute=0, second=0, microsecond=0)
# API fetch range depends on include_tomorrow flag
if include_tomorrow:
fetch_end_time = end_of_tomorrow
fetch_desc = "end-of-tomorrow"
else:
# Only fetch up to end of today (prevents API spam before 13:00)
fetch_end_time = (now_local + timedelta(days=1)).replace(hour=0, minute=0, second=0, microsecond=0)
fetch_desc = "end-of-today"
_LOGGER.debug(
"Sensor data request for home %s: fetch %s to %s (%s), return up to %s",
self._home_id,
day_before_yesterday.isoformat(),
fetch_end_time.isoformat(),
fetch_desc,
end_of_tomorrow.isoformat(),
)
# Fetch data (may be partial if include_tomorrow=False)
_intervals, api_called = await self.get_intervals(
api_client=api_client,
user_data=user_data,
start_time=day_before_yesterday,
end_time=fetch_end_time,
)
# Return FULL protected range (including any cached tomorrow data)
# This ensures cached tomorrow data is available even when include_tomorrow=False
final_intervals = self._get_cached_intervals(
day_before_yesterday.isoformat(),
end_of_tomorrow.isoformat(),
)
return final_intervals, api_called
def get_pool_stats(self) -> dict[str, Any]:
"""
Get statistics about the interval pool.
Returns comprehensive statistics for diagnostic sensors, separated into:
- Sensor intervals (protected range: day-before-yesterday to tomorrow)
- Cache statistics (entire pool including service-requested data)
Protected Range:
The protected range covers 4 days at 15-min resolution = 384 intervals.
These intervals are never evicted by garbage collection.
Cache Fill Level:
Shows how full the cache is relative to MAX_CACHE_SIZE (960).
100% is not bad - just means we're using the available space.
GC will evict oldest non-protected intervals when limit is reached.
Returns:
Dict with sensor intervals, cache stats, and timestamps.
"""
fetch_groups = self._cache.get_fetch_groups()
# === Sensor Intervals (Protected Range) ===
sensor_stats = self._get_sensor_interval_stats()
# === Cache Statistics (Entire Pool) ===
cache_total = self._index.count()
cache_limit = MAX_CACHE_SIZE
cache_fill_percent = round((cache_total / cache_limit) * 100, 1) if cache_limit > 0 else 0
cache_extra = max(0, cache_total - sensor_stats["count"]) # Intervals outside protected range
# === Timestamps ===
# Last sensor fetch (for protected range data)
last_sensor_fetch: str | None = None
oldest_interval: str | None = None
newest_interval: str | None = None
if fetch_groups:
# Find newest fetch group (most recent API call)
newest_group = max(fetch_groups, key=lambda g: g["fetched_at"])
last_sensor_fetch = newest_group["fetched_at"].isoformat()
# Find oldest and newest intervals across all fetch groups
all_timestamps = list(self._index.get_raw_index().keys())
if all_timestamps:
oldest_interval = min(all_timestamps)
newest_interval = max(all_timestamps)
return {
# Sensor intervals (protected range)
"sensor_intervals_count": sensor_stats["count"],
"sensor_intervals_expected": sensor_stats["expected"],
"sensor_intervals_has_gaps": sensor_stats["has_gaps"],
# Cache statistics
"cache_intervals_total": cache_total,
"cache_intervals_limit": cache_limit,
"cache_fill_percent": cache_fill_percent,
"cache_intervals_extra": cache_extra,
# Timestamps
"last_sensor_fetch": last_sensor_fetch,
"cache_oldest_interval": oldest_interval,
"cache_newest_interval": newest_interval,
# Fetch groups (API calls)
"fetch_groups_count": len(fetch_groups),
}
def _get_sensor_interval_stats(self) -> dict[str, Any]:
"""
Get statistics for sensor intervals (protected range).
Protected range: day-before-yesterday 00:00 to day-after-tomorrow 00:00.
Expected: 4 days * 24 hours * 4 intervals = 384 intervals.
Returns:
Dict with count, expected, and has_gaps.
"""
start_iso, end_iso = self._cache.get_protected_range()
start_dt = datetime.fromisoformat(start_iso)
end_dt = datetime.fromisoformat(end_iso)
# Count expected intervals (15-min resolution)
expected_count = int((end_dt - start_dt).total_seconds() / (15 * 60))
# Count actual intervals in range
actual_count = 0
current_dt = start_dt
while current_dt < end_dt:
current_key = current_dt.isoformat()[:19]
if self._index.contains(current_key):
actual_count += 1
current_dt += timedelta(minutes=15)
return {
"count": actual_count,
"expected": expected_count,
"has_gaps": actual_count < expected_count,
}
def _has_gaps_in_protected_range(self) -> bool:
"""
Check if there are gaps in the protected date range.
Delegates to _get_sensor_interval_stats() for consistency.
Returns:
True if any gaps exist, False if protected range is complete.
"""
return self._get_sensor_interval_stats()["has_gaps"]
def _extract_timezone_from_user_data(self, user_data: dict[str, Any]) -> str | None:
"""Extract timezone for this home from user_data."""
if not user_data:
return None
viewer = user_data.get("viewer", {})
homes = viewer.get("homes", [])
for home in homes:
if home.get("id") == self._home_id:
return home.get("timeZone")
return None
def _get_cached_intervals(
self,
start_time_iso: str,
end_time_iso: str,
) -> list[dict[str, Any]]:
"""
Get cached intervals for time range using timestamp index.
Uses timestamp_index for O(1) lookups per timestamp.
IMPORTANT: Returns shallow copies of interval dicts to prevent external
mutations (e.g., by parse_all_timestamps()) from affecting cached data.
The Pool cache must remain immutable to ensure consistent behavior.
Args:
start_time_iso: ISO timestamp string (inclusive).
end_time_iso: ISO timestamp string (exclusive).
Returns:
List of cached interval dicts in time range (may be empty or incomplete).
Sorted by startsAt timestamp. Each dict is a shallow copy.
"""
# Parse query range once
start_time_dt = datetime.fromisoformat(start_time_iso)
end_time_dt = datetime.fromisoformat(end_time_iso)
# CRITICAL: Use NAIVE local timestamps for iteration.
#
# Index keys are naive local timestamps (timezone stripped via [:19]).
# When start and end span a DST transition, they have different UTC offsets
# (e.g., start=+01:00 CET, end=+02:00 CEST). Using fixed-offset datetimes
# from fromisoformat() causes the loop to compare UTC values for the end
# boundary, ending 1 hour early on spring-forward days (or 1 hour late on
# fall-back days).
#
# By iterating in naive local time, we match the index key format exactly
# and the end boundary comparison works correctly regardless of DST.
current_naive = start_time_dt.replace(tzinfo=None)
end_naive = end_time_dt.replace(tzinfo=None)
# Use index to find intervals: iterate through expected timestamps
result = []
# Determine interval step (15 min post-2025-10-01, 60 min pre)
resolution_change_naive = datetime(2025, 10, 1) # noqa: DTZ001
interval_minutes = INTERVAL_QUARTER_HOURLY if current_naive >= resolution_change_naive else INTERVAL_HOURLY
while current_naive < end_naive:
# Check if this timestamp exists in index (O(1) lookup)
current_dt_key = current_naive.isoformat()[:19]
location = self._index.get(current_dt_key)
if location is not None:
# Get interval from fetch group
fetch_groups = self._cache.get_fetch_groups()
fetch_group = fetch_groups[location["fetch_group_index"]]
interval = fetch_group["intervals"][location["interval_index"]]
# CRITICAL: Return shallow copy to prevent external mutations
# (e.g., parse_all_timestamps() converts startsAt to datetime in-place)
result.append(dict(interval))
# Move to next expected interval
current_naive += timedelta(minutes=interval_minutes)
# Handle resolution change boundary
if interval_minutes == INTERVAL_HOURLY and current_naive >= resolution_change_naive:
interval_minutes = INTERVAL_QUARTER_HOURLY
_LOGGER_DETAILS.debug(
"Retrieved %d intervals from cache for home %s (range %s to %s)",
len(result),
self._home_id,
start_time_iso,
end_time_iso,
)
return result
def _add_intervals(
self,
intervals: list[dict[str, Any]],
fetch_time_iso: str,
) -> None:
"""
Add intervals as new fetch group to cache with GC.
Strategy:
1. Filter out duplicates (intervals already in cache)
2. Handle "touch" (move cached intervals to new fetch group)
3. Add new fetch group to cache
4. Update timestamp index
5. Run GC if needed
6. Schedule debounced auto-save
Args:
intervals: List of interval dicts from API.
fetch_time_iso: ISO timestamp string when intervals were fetched.
"""
if not intervals:
return
fetch_time_dt = datetime.fromisoformat(fetch_time_iso)
# Classify intervals: new vs already cached
new_intervals = []
intervals_to_touch = []
for interval in intervals:
starts_at_normalized = _normalize_starts_at(interval["startsAt"])
if not self._index.contains(starts_at_normalized):
new_intervals.append(interval)
else:
intervals_to_touch.append((starts_at_normalized, interval))
_LOGGER_DETAILS.debug(
"Interval %s already cached for home %s, will touch (update fetch time)",
interval["startsAt"],
self._home_id,
)
# Handle touched intervals: move to new fetch group
if intervals_to_touch:
self._touch_intervals(intervals_to_touch, fetch_time_dt)
if not new_intervals:
if intervals_to_touch:
_LOGGER_DETAILS.debug(
"All %d intervals already cached for home %s (touched only)",
len(intervals),
self._home_id,
)
return
# Sort new intervals by startsAt
new_intervals.sort(key=lambda x: x["startsAt"])
# Add new fetch group to cache
fetch_group_index = self._cache.add_fetch_group(new_intervals, fetch_time_dt)
# Update timestamp index for all new intervals
for interval_index, interval in enumerate(new_intervals):
starts_at_normalized = _normalize_starts_at(interval["startsAt"])
self._index.add(interval, fetch_group_index, interval_index)
_LOGGER_DETAILS.debug(
"Added fetch group %d to home %s cache: %d new intervals (fetched at %s)",
fetch_group_index,
self._home_id,
len(new_intervals),
fetch_time_iso,
)
# Run GC to evict old fetch groups if needed
gc_changed_data = self._gc.run_gc()
# Schedule debounced auto-save if data changed
data_changed = len(new_intervals) > 0 or len(intervals_to_touch) > 0 or gc_changed_data
if data_changed and self._hass is not None and self._entry_id is not None:
self._schedule_debounced_save()
def _touch_intervals(
self,
intervals_to_touch: list[tuple[str, dict[str, Any]]],
fetch_time_dt: datetime,
) -> None:
"""
Move cached intervals to new fetch group (update fetch time).
Creates a new fetch group containing references to existing intervals.
Updates the index to point to the new fetch group.
Args:
intervals_to_touch: List of (normalized_timestamp, interval_dict) tuples.
fetch_time_dt: Datetime when intervals were fetched.
"""
fetch_groups = self._cache.get_fetch_groups()
# Create touch fetch group with existing interval references
touch_intervals = []
for starts_at_normalized, _interval in intervals_to_touch:
# Get existing interval from old fetch group
location = self._index.get(starts_at_normalized)
if location is None:
continue # Should not happen, but be defensive
old_group = fetch_groups[location["fetch_group_index"]]
existing_interval = old_group["intervals"][location["interval_index"]]
touch_intervals.append(existing_interval)
# Add touch group to cache
touch_group_index = self._cache.add_fetch_group(touch_intervals, fetch_time_dt)
# Update index to point to new fetch group using batch operation
# This is more efficient than individual remove+add calls
index_updates = [
(starts_at_normalized, touch_group_index, interval_index)
for interval_index, (starts_at_normalized, _) in enumerate(intervals_to_touch)
]
self._index.update_batch(index_updates)
_LOGGER.debug(
"Touched %d cached intervals for home %s (moved to fetch group %d, fetched at %s)",
len(intervals_to_touch),
self._home_id,
touch_group_index,
fetch_time_dt.isoformat(),
)
def _schedule_debounced_save(self) -> None:
"""
Schedule debounced save with configurable delay.
Cancels existing timer and starts new one if already scheduled.
This prevents multiple saves during rapid successive changes.
"""
# Cancel existing debounce timer if running
if self._save_debounce_task is not None and not self._save_debounce_task.done():
self._save_debounce_task.cancel()
_LOGGER.debug("Cancelled pending auto-save (new changes detected, resetting timer)")
# Schedule new debounced save
task = asyncio.create_task(
self._debounced_save_worker(),
name=f"interval_pool_debounce_{self._entry_id}",
)
self._save_debounce_task = task
self._background_tasks.add(task)
task.add_done_callback(self._background_tasks.discard)
async def _debounced_save_worker(self) -> None:
"""Debounce worker: waits configured delay, then saves if not cancelled."""
try:
await asyncio.sleep(DEBOUNCE_DELAY_SECONDS)
await self._auto_save_pool_state()
except asyncio.CancelledError:
_LOGGER.debug("Auto-save timer cancelled (expected - new changes arrived)")
raise
async def async_shutdown(self) -> None:
"""
Clean shutdown - cancel pending background tasks.
Should be called when the config entry is unloaded to prevent
orphaned tasks and ensure clean resource cleanup.
"""
_LOGGER.debug("Shutting down interval pool for home %s", self._home_id)
# Cancel debounce task if running
if self._save_debounce_task is not None and not self._save_debounce_task.done():
self._save_debounce_task.cancel()
with contextlib.suppress(asyncio.CancelledError):
await self._save_debounce_task
_LOGGER.debug("Cancelled pending auto-save task")
# Cancel any other background tasks
if self._background_tasks:
for task in list(self._background_tasks):
if not task.done():
task.cancel()
# Wait for all tasks to complete cancellation
if self._background_tasks:
await asyncio.gather(*self._background_tasks, return_exceptions=True)
_LOGGER.debug("Cancelled %d background tasks", len(self._background_tasks))
self._background_tasks.clear()
_LOGGER.debug("Interval pool shutdown complete for home %s", self._home_id)
async def _auto_save_pool_state(self) -> None:
"""Auto-save pool state to storage with lock protection."""
if self._hass is None or self._entry_id is None:
return
async with self._save_lock:
try:
pool_state = self.to_dict()
await async_save_pool_state(self._hass, self._entry_id, pool_state)
_LOGGER.debug("Auto-saved interval pool for entry %s", self._entry_id)
except Exception:
_LOGGER.exception("Failed to auto-save interval pool for entry %s", self._entry_id)
def to_dict(self) -> dict[str, Any]:
"""
Serialize interval pool state for storage.
Filters out dead intervals (no longer referenced by index).
Returns:
Dictionary containing serialized pool state (only living intervals).
"""
fetch_groups = self._cache.get_fetch_groups()
# Serialize fetch groups (only living intervals)
serialized_fetch_groups = []
for group_idx, fetch_group in enumerate(fetch_groups):
living_intervals = []
for interval_idx, interval in enumerate(fetch_group["intervals"]):
starts_at_normalized = _normalize_starts_at(interval["startsAt"])
# Check if interval is still referenced in index
location = self._index.get(starts_at_normalized)
# Only keep if index points to THIS position in THIS group
if (
location is not None
and location["fetch_group_index"] == group_idx
and location["interval_index"] == interval_idx
):
living_intervals.append(interval)
# Only serialize groups with living intervals
if living_intervals:
serialized_fetch_groups.append(
{
"fetched_at": fetch_group["fetched_at"].isoformat(),
"intervals": living_intervals,
}
)
return {
"version": 1,
"home_id": self._home_id,
"fetch_groups": serialized_fetch_groups,
}
@classmethod
def from_dict(
cls,
data: dict[str, Any],
*,
api: TibberPricesApiClient,
hass: Any | None = None,
entry_id: str | None = None,
time_service: TibberPricesTimeService | None = None,
) -> TibberPricesIntervalPool | None:
"""
Restore interval pool manager from storage.
Expects single-home format: {"version": 1, "home_id": "...", "fetch_groups": [...]}
Old multi-home format is treated as corrupted and returns None.
Args:
data: Dictionary containing serialized pool state.
api: API client for fetching intervals.
hass: HomeAssistant instance for auto-save (optional).
entry_id: Config entry ID for auto-save (optional).
time_service: TimeService for time-travel support (optional).
Returns:
Restored TibberPricesIntervalPool instance, or None if format unknown/corrupted.
"""
# Validate format
if not data or "home_id" not in data or "fetch_groups" not in data:
if "homes" in data:
_LOGGER.info(
"Interval pool storage uses old multi-home format (pre-2025-11-25). "
"Treating as corrupted. Pool will rebuild from API."
)
else:
_LOGGER.warning("Interval pool storage format unknown or corrupted. Pool will rebuild from API.")
return None
home_id = data["home_id"]
# Create manager with home_id from storage
manager = cls(home_id=home_id, api=api, hass=hass, entry_id=entry_id, time_service=time_service)
# Restore fetch groups to cache
for serialized_group in data.get("fetch_groups", []):
fetched_at_dt = datetime.fromisoformat(serialized_group["fetched_at"])
intervals = serialized_group["intervals"]
fetch_group_index = manager._cache.add_fetch_group(intervals, fetched_at_dt)
# Rebuild index for this fetch group
for interval_index, interval in enumerate(intervals):
manager._index.add(interval, fetch_group_index, interval_index)
total_intervals = sum(len(group["intervals"]) for group in manager._cache.get_fetch_groups())
_LOGGER.debug(
"Interval pool restored from storage (home %s, %d intervals)",
home_id,
total_intervals,
)
return manager

View file

@ -1,180 +0,0 @@
"""
Routing Module - API endpoint selection for price intervals.
This module handles intelligent routing between different Tibber API endpoints:
- PRICE_INFO: Recent data (from "day before yesterday midnight" onwards)
- PRICE_INFO_RANGE: Historical data (before "day before yesterday midnight")
- Automatic splitting and merging when range spans the boundary
CRITICAL: Uses REAL TIME (dt_utils.now()) for API boundary calculation,
NOT TimeService.now() which may be shifted for internal simulation.
"""
from __future__ import annotations
import logging
from typing import TYPE_CHECKING, Any
from custom_components.tibber_prices.api.exceptions import TibberPricesApiClientError
from homeassistant.util import dt as dt_utils
if TYPE_CHECKING:
from datetime import datetime
from custom_components.tibber_prices.api.client import TibberPricesApiClient
_LOGGER = logging.getLogger(__name__)
_LOGGER_DETAILS = logging.getLogger(__name__ + ".details")
async def get_price_intervals_for_range(
api_client: TibberPricesApiClient,
home_id: str,
user_data: dict[str, Any],
start_time: datetime,
end_time: datetime,
) -> list[dict[str, Any]]:
"""
Get price intervals for a specific time range with automatic routing.
Automatically routes to the correct API endpoint based on the time range:
- PRICE_INFO_RANGE: For intervals exclusively before "day before yesterday midnight" (real time)
- PRICE_INFO: For intervals from "day before yesterday midnight" onwards
- Both: If range spans across the boundary, splits the request
CRITICAL: Uses REAL TIME (dt_utils.now()) for API boundary calculation,
NOT TimeService.now() which may be shifted for internal simulation.
This ensures predictable API responses.
CACHING STRATEGY: Returns ALL intervals from API response, NOT filtered.
The caller (pool.py) will cache everything and then filter to user request.
This maximizes cache efficiency - one API call can populate cache for
multiple subsequent queries.
Args:
api_client: TibberPricesApiClient instance for API calls.
home_id: Home ID to fetch price data for.
user_data: User data dict containing home metadata (including timezone).
start_time: Start of the range (inclusive, timezone-aware).
end_time: End of the range (exclusive, timezone-aware).
Returns:
List of ALL price interval dicts from API (unfiltered).
- PRICE_INFO: Returns ~384 intervals (day-before-yesterday to tomorrow)
- PRICE_INFO_RANGE: Returns intervals for requested historical range
- Both: Returns all intervals from both endpoints
Raises:
TibberPricesApiClientError: If arguments invalid or requests fail.
"""
if not user_data:
msg = "User data required for timezone-aware price fetching - fetch user data first"
raise TibberPricesApiClientError(msg)
if not home_id:
msg = "Home ID is required"
raise TibberPricesApiClientError(msg)
if start_time >= end_time:
msg = f"Invalid time range: start_time ({start_time}) must be before end_time ({end_time})"
raise TibberPricesApiClientError(msg)
# Calculate boundary: day before yesterday midnight (REAL TIME, not TimeService)
boundary = _calculate_boundary(api_client, user_data, home_id)
_LOGGER_DETAILS.debug(
"Routing price interval request for home %s: range %s to %s, boundary %s",
home_id,
start_time,
end_time,
boundary,
)
# Route based on time range
if end_time <= boundary:
# Entire range is historical (before day before yesterday) → use PRICE_INFO_RANGE
_LOGGER_DETAILS.debug("Range is fully historical, using PRICE_INFO_RANGE")
result = await api_client.async_get_price_info_range(
home_id=home_id,
user_data=user_data,
start_time=start_time,
end_time=end_time,
)
return result["price_info"]
if start_time >= boundary:
# Entire range is recent (from day before yesterday onwards) → use PRICE_INFO
_LOGGER_DETAILS.debug("Range is fully recent, using PRICE_INFO")
result = await api_client.async_get_price_info(home_id, user_data)
# Return ALL intervals (unfiltered) for maximum cache efficiency
# Pool will cache everything, then filter to user request
return result["price_info"]
# Range spans boundary → split request
_LOGGER_DETAILS.debug("Range spans boundary, splitting request")
# Fetch historical part (start_time to boundary)
historical_result = await api_client.async_get_price_info_range(
home_id=home_id,
user_data=user_data,
start_time=start_time,
end_time=boundary,
)
# Fetch recent part (boundary onwards)
recent_result = await api_client.async_get_price_info(home_id, user_data)
# Return ALL intervals (unfiltered) for maximum cache efficiency
# Pool will cache everything, then filter to user request
return historical_result["price_info"] + recent_result["price_info"]
def _calculate_boundary(
api_client: TibberPricesApiClient,
user_data: dict[str, Any],
home_id: str,
) -> datetime:
"""
Calculate the API boundary (day before yesterday midnight).
Uses the API client's helper method to extract timezone and calculate boundary.
Args:
api_client: TibberPricesApiClient instance.
user_data: User data dict containing home metadata.
home_id: Home ID to get timezone for.
Returns:
Timezone-aware datetime for day before yesterday midnight.
"""
# Extract timezone for this home
home_timezones = api_client._extract_home_timezones(user_data) # noqa: SLF001
home_tz = home_timezones.get(home_id)
# Calculate boundary using API client's method
return api_client._calculate_day_before_yesterday_midnight(home_tz) # noqa: SLF001
def _parse_timestamp(timestamp_str: str) -> datetime:
"""
Parse ISO timestamp string to timezone-aware datetime.
Args:
timestamp_str: ISO format timestamp string.
Returns:
Timezone-aware datetime object.
Raises:
ValueError: If timestamp string cannot be parsed.
"""
result = dt_utils.parse_datetime(timestamp_str)
if result is None:
msg = f"Failed to parse timestamp: {timestamp_str}"
raise ValueError(msg)
return result

View file

@ -1,165 +0,0 @@
"""Storage management for interval pool."""
from __future__ import annotations
import errno
import logging
from typing import TYPE_CHECKING, Any
from homeassistant.helpers.storage import Store
if TYPE_CHECKING:
from homeassistant.core import HomeAssistant
_LOGGER = logging.getLogger(__name__)
_LOGGER_DETAILS = logging.getLogger(__name__ + ".details")
# Storage version - increment when changing data structure
INTERVAL_POOL_STORAGE_VERSION = 1
def get_storage_key(entry_id: str) -> str:
"""
Get storage key for interval pool based on config entry ID.
Args:
entry_id: Home Assistant config entry ID
Returns:
Storage key string
"""
return f"tibber_prices.interval_pool.{entry_id}"
async def async_load_pool_state(
hass: HomeAssistant,
entry_id: str,
) -> dict[str, Any] | None:
"""
Load interval pool state from storage.
Args:
hass: Home Assistant instance
entry_id: Config entry ID
Returns:
Pool state dict or None if no cache exists
"""
storage_key = get_storage_key(entry_id)
store: Store = Store(hass, INTERVAL_POOL_STORAGE_VERSION, storage_key)
try:
stored = await store.async_load()
except Exception:
# Corrupted storage file, JSON parse error, or other exception
_LOGGER.exception(
"Failed to load interval pool storage for entry %s (corrupted file?), starting with empty pool",
entry_id,
)
return None
if stored is None:
_LOGGER.debug("No interval pool cache found for entry %s (first run)", entry_id)
return None
# Validate storage structure (single-home format)
if not isinstance(stored, dict):
_LOGGER.warning(
"Invalid interval pool storage structure for entry %s (not a dict), ignoring",
entry_id,
)
return None
# Check for new single-home format (version 1, home_id, fetch_groups)
if "home_id" in stored and "fetch_groups" in stored:
_LOGGER.debug(
"Interval pool state loaded for entry %s (single-home format, %d fetch groups)",
entry_id,
len(stored.get("fetch_groups", [])),
)
return stored
# Check for old multi-home format (homes dict) - treat as incompatible
if "homes" in stored:
_LOGGER.info(
"Interval pool storage for entry %s uses old multi-home format (pre-2025-11-25). "
"Treating as incompatible. Pool will rebuild from API.",
entry_id,
)
return None
# Unknown format
_LOGGER.warning(
"Invalid interval pool storage structure for entry %s (missing required keys), ignoring",
entry_id,
)
return None
async def async_save_pool_state(
hass: HomeAssistant,
entry_id: str,
pool_state: dict[str, Any],
) -> None:
"""
Save interval pool state to storage.
Args:
hass: Home Assistant instance
entry_id: Config entry ID
pool_state: Pool state dict to save
"""
storage_key = get_storage_key(entry_id)
store: Store = Store(hass, INTERVAL_POOL_STORAGE_VERSION, storage_key)
try:
await store.async_save(pool_state)
_LOGGER_DETAILS.debug(
"Interval pool state saved for entry %s (%d fetch groups)",
entry_id,
len(pool_state.get("fetch_groups", [])),
)
except OSError as err:
# Provide specific error messages based on errno
if err.errno == errno.ENOSPC: # Disk full
_LOGGER.exception(
"Cannot save interval pool storage for entry %s: Disk full!",
entry_id,
)
elif err.errno == errno.EACCES: # Permission denied
_LOGGER.exception(
"Cannot save interval pool storage for entry %s: Permission denied!",
entry_id,
)
else:
_LOGGER.exception(
"Failed to save interval pool storage for entry %s",
entry_id,
)
async def async_remove_pool_storage(
hass: HomeAssistant,
entry_id: str,
) -> None:
"""
Remove interval pool storage file.
Used when config entry is removed.
Args:
hass: Home Assistant instance
entry_id: Config entry ID
"""
storage_key = get_storage_key(entry_id)
store: Store = Store(hass, INTERVAL_POOL_STORAGE_VERSION, storage_key)
try:
await store.async_remove()
_LOGGER.debug("Interval pool storage removed for entry %s", entry_id)
except OSError as ex:
_LOGGER.warning("Failed to remove interval pool storage for entry %s: %s", entry_id, ex)

View file

@ -6,10 +6,11 @@
],
"config_flow": true,
"documentation": "https://github.com/jpawlowski/hass.tibber_prices",
"integration_type": "hub",
"iot_class": "cloud_polling",
"issue_tracker": "https://github.com/jpawlowski/hass.tibber_prices/issues",
"requirements": [
"aiofiles>=23.2.1"
],
"version": "0.27.0"
"version": "0.10.1"
}

View file

@ -1,39 +0,0 @@
"""
Number platform for Tibber Prices integration.
Provides configurable number entities for runtime overrides of Best Price
and Peak Price period calculation settings. These entities allow automation
of configuration parameters without using the options flow.
When enabled, these entities take precedence over the options flow settings.
When disabled (default), the options flow settings are used.
"""
from __future__ import annotations
from typing import TYPE_CHECKING
from .core import TibberPricesConfigNumber
from .definitions import NUMBER_ENTITY_DESCRIPTIONS
if TYPE_CHECKING:
from custom_components.tibber_prices.data import TibberPricesConfigEntry
from homeassistant.core import HomeAssistant
from homeassistant.helpers.entity_platform import AddEntitiesCallback
async def async_setup_entry(
_hass: HomeAssistant,
entry: TibberPricesConfigEntry,
async_add_entities: AddEntitiesCallback,
) -> None:
"""Set up Tibber Prices number entities based on a config entry."""
coordinator = entry.runtime_data.coordinator
async_add_entities(
TibberPricesConfigNumber(
coordinator=coordinator,
entity_description=entity_description,
)
for entity_description in NUMBER_ENTITY_DESCRIPTIONS
)

View file

@ -1,242 +0,0 @@
"""
Number entity implementation for Tibber Prices configuration overrides.
These entities allow runtime configuration of period calculation settings.
When a config entity is enabled, its value takes precedence over the
options flow setting for period calculations.
"""
from __future__ import annotations
import logging
from typing import TYPE_CHECKING, Any
from custom_components.tibber_prices.const import (
DOMAIN,
get_home_type_translation,
get_translation,
)
from homeassistant.components.number import NumberEntity, RestoreNumber
from homeassistant.core import callback
from homeassistant.helpers.device_registry import DeviceEntryType, DeviceInfo
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator import (
TibberPricesDataUpdateCoordinator,
)
from .definitions import TibberPricesNumberEntityDescription
_LOGGER = logging.getLogger(__name__)
class TibberPricesConfigNumber(RestoreNumber, NumberEntity):
"""
A number entity for configuring period calculation settings at runtime.
When this entity is enabled, its value overrides the corresponding
options flow setting. When disabled (default), the options flow
setting is used for period calculations.
The entity restores its value after Home Assistant restart.
"""
_attr_has_entity_name = True
entity_description: TibberPricesNumberEntityDescription
# Exclude all attributes from recorder history - config entities don't need history
_unrecorded_attributes = frozenset(
{
"description",
"long_description",
"usage_tips",
"friendly_name",
"icon",
"unit_of_measurement",
"mode",
"min",
"max",
"step",
}
)
def __init__(
self,
coordinator: TibberPricesDataUpdateCoordinator,
entity_description: TibberPricesNumberEntityDescription,
) -> None:
"""Initialize the config number entity."""
self.coordinator = coordinator
self.entity_description = entity_description
# Set unique ID
self._attr_unique_id = (
f"{coordinator.config_entry.unique_id or coordinator.config_entry.entry_id}_{entity_description.key}"
)
# Initialize with None - will be set in async_added_to_hass
self._attr_native_value: float | None = None
# Setup device info
self._setup_device_info()
def _setup_device_info(self) -> None:
"""Set up device information."""
home_name, home_id, home_type = self._get_device_info()
language = self.coordinator.hass.config.language or "en"
translated_model = get_home_type_translation(home_type, language) if home_type else "Unknown"
self._attr_device_info = DeviceInfo(
entry_type=DeviceEntryType.SERVICE,
identifiers={
(
DOMAIN,
self.coordinator.config_entry.unique_id or self.coordinator.config_entry.entry_id,
)
},
name=home_name,
manufacturer="Tibber",
model=translated_model,
serial_number=home_id if home_id else None,
configuration_url="https://developer.tibber.com/explorer",
)
def _get_device_info(self) -> tuple[str, str | None, str | None]:
"""Get device name, ID and type."""
user_profile = self.coordinator.get_user_profile()
is_subentry = bool(self.coordinator.config_entry.data.get("home_id"))
home_id = self.coordinator.config_entry.unique_id
home_type = None
if is_subentry:
home_data = self.coordinator.config_entry.data.get("home_data", {})
home_id = self.coordinator.config_entry.data.get("home_id")
address = home_data.get("address", {})
address1 = address.get("address1", "")
city = address.get("city", "")
app_nickname = home_data.get("appNickname", "")
home_type = home_data.get("type", "")
if app_nickname and app_nickname.strip():
home_name = app_nickname.strip()
elif address1:
home_name = address1
if city:
home_name = f"{home_name}, {city}"
else:
home_name = f"Tibber Home {home_id[:8]}" if home_id else "Tibber Home"
elif user_profile:
home_name = user_profile.get("name") or "Tibber Home"
else:
home_name = "Tibber Home"
return home_name, home_id, home_type
async def async_added_to_hass(self) -> None:
"""Handle entity which was added to Home Assistant."""
await super().async_added_to_hass()
# Try to restore previous state
last_number_data = await self.async_get_last_number_data()
if last_number_data is not None and last_number_data.native_value is not None:
self._attr_native_value = last_number_data.native_value
_LOGGER.debug(
"Restored %s value: %s",
self.entity_description.key,
self._attr_native_value,
)
else:
# Initialize with value from options flow (or default)
self._attr_native_value = self._get_value_from_options()
_LOGGER.debug(
"Initialized %s from options: %s",
self.entity_description.key,
self._attr_native_value,
)
# Register override with coordinator if entity is enabled
# This happens during add, so check entity registry
await self._sync_override_state()
async def async_will_remove_from_hass(self) -> None:
"""Handle entity removal from Home Assistant."""
# Remove override when entity is removed
self.coordinator.remove_config_override(
self.entity_description.config_key,
self.entity_description.config_section,
)
await super().async_will_remove_from_hass()
def _get_value_from_options(self) -> float:
"""Get the current value from options flow or default."""
options = self.coordinator.config_entry.options
section = options.get(self.entity_description.config_section, {})
value = section.get(
self.entity_description.config_key,
self.entity_description.default_value,
)
return float(value)
async def _sync_override_state(self) -> None:
"""Sync the override state with the coordinator based on entity enabled state."""
# Check if entity is enabled in registry
if self.registry_entry is not None and not self.registry_entry.disabled:
# Entity is enabled - register the override
if self._attr_native_value is not None:
self.coordinator.set_config_override(
self.entity_description.config_key,
self.entity_description.config_section,
self._attr_native_value,
)
else:
# Entity is disabled - remove override
self.coordinator.remove_config_override(
self.entity_description.config_key,
self.entity_description.config_section,
)
async def async_set_native_value(self, value: float) -> None:
"""Update the current value and trigger recalculation."""
self._attr_native_value = value
# Update the coordinator's runtime override
self.coordinator.set_config_override(
self.entity_description.config_key,
self.entity_description.config_section,
value,
)
# Trigger period recalculation (same path as options update)
await self.coordinator.async_handle_config_override_update()
_LOGGER.debug(
"Updated %s to %s, triggered period recalculation",
self.entity_description.key,
value,
)
@property
def extra_state_attributes(self) -> dict[str, Any] | None:
"""Return entity state attributes with description."""
language = self.coordinator.hass.config.language or "en"
# Try to get description from custom translations
# Custom translations use direct path: number.{key}.description
translation_path = [
"number",
self.entity_description.translation_key or self.entity_description.key,
"description",
]
description = get_translation(translation_path, language)
attrs: dict[str, Any] = {}
if description:
attrs["description"] = description
return attrs if attrs else None
@callback
def async_registry_entry_updated(self) -> None:
"""Handle entity registry update (enabled/disabled state change)."""
# This is called when the entity is enabled/disabled in the UI
self.hass.async_create_task(self._sync_override_state())

View file

@ -1,250 +0,0 @@
"""
Number entity definitions for Tibber Prices configuration overrides.
These number entities allow runtime configuration of Best Price and Peak Price
period calculation settings. They are disabled by default - users can enable
individual entities to override specific settings at runtime.
When enabled, the entity value takes precedence over the options flow setting.
When disabled (default), the options flow setting is used.
"""
from __future__ import annotations
from dataclasses import dataclass
from homeassistant.components.number import (
NumberEntityDescription,
NumberMode,
)
from homeassistant.const import PERCENTAGE, EntityCategory
@dataclass(frozen=True, kw_only=True)
class TibberPricesNumberEntityDescription(NumberEntityDescription):
"""Describes a Tibber Prices number entity for config overrides."""
# The config key this entity overrides (matches CONF_* constants)
config_key: str
# The section in options where this setting is stored (e.g., "flexibility_settings")
config_section: str
# Whether this is for best_price (False) or peak_price (True)
is_peak_price: bool = False
# Default value from const.py
default_value: float | int = 0
# ============================================================================
# BEST PRICE PERIOD CONFIGURATION OVERRIDES
# ============================================================================
BEST_PRICE_NUMBER_ENTITIES = (
TibberPricesNumberEntityDescription(
key="best_price_flex_override",
translation_key="best_price_flex_override",
name="Best Price: Flexibility",
icon="mdi:arrow-down-bold-circle",
entity_category=EntityCategory.CONFIG,
entity_registry_enabled_default=False,
native_min_value=0,
native_max_value=50,
native_step=1,
native_unit_of_measurement=PERCENTAGE,
mode=NumberMode.SLIDER,
config_key="best_price_flex",
config_section="flexibility_settings",
is_peak_price=False,
default_value=15, # DEFAULT_BEST_PRICE_FLEX
),
TibberPricesNumberEntityDescription(
key="best_price_min_distance_override",
translation_key="best_price_min_distance_override",
name="Best Price: Minimum Distance",
icon="mdi:arrow-down-bold-circle",
entity_category=EntityCategory.CONFIG,
entity_registry_enabled_default=False,
native_min_value=-50,
native_max_value=0,
native_step=1,
native_unit_of_measurement=PERCENTAGE,
mode=NumberMode.SLIDER,
config_key="best_price_min_distance_from_avg",
config_section="flexibility_settings",
is_peak_price=False,
default_value=-5, # DEFAULT_BEST_PRICE_MIN_DISTANCE_FROM_AVG
),
TibberPricesNumberEntityDescription(
key="best_price_min_period_length_override",
translation_key="best_price_min_period_length_override",
name="Best Price: Minimum Period Length",
icon="mdi:arrow-down-bold-circle",
entity_category=EntityCategory.CONFIG,
entity_registry_enabled_default=False,
native_min_value=15,
native_max_value=180,
native_step=15,
native_unit_of_measurement="min",
mode=NumberMode.SLIDER,
config_key="best_price_min_period_length",
config_section="period_settings",
is_peak_price=False,
default_value=60, # DEFAULT_BEST_PRICE_MIN_PERIOD_LENGTH
),
TibberPricesNumberEntityDescription(
key="best_price_min_periods_override",
translation_key="best_price_min_periods_override",
name="Best Price: Minimum Periods",
icon="mdi:arrow-down-bold-circle",
entity_category=EntityCategory.CONFIG,
entity_registry_enabled_default=False,
native_min_value=1,
native_max_value=10,
native_step=1,
mode=NumberMode.SLIDER,
config_key="min_periods_best",
config_section="relaxation_and_target_periods",
is_peak_price=False,
default_value=2, # DEFAULT_MIN_PERIODS_BEST
),
TibberPricesNumberEntityDescription(
key="best_price_relaxation_attempts_override",
translation_key="best_price_relaxation_attempts_override",
name="Best Price: Relaxation Attempts",
icon="mdi:arrow-down-bold-circle",
entity_category=EntityCategory.CONFIG,
entity_registry_enabled_default=False,
native_min_value=1,
native_max_value=12,
native_step=1,
mode=NumberMode.SLIDER,
config_key="relaxation_attempts_best",
config_section="relaxation_and_target_periods",
is_peak_price=False,
default_value=11, # DEFAULT_RELAXATION_ATTEMPTS_BEST
),
TibberPricesNumberEntityDescription(
key="best_price_gap_count_override",
translation_key="best_price_gap_count_override",
name="Best Price: Gap Tolerance",
icon="mdi:arrow-down-bold-circle",
entity_category=EntityCategory.CONFIG,
entity_registry_enabled_default=False,
native_min_value=0,
native_max_value=8,
native_step=1,
mode=NumberMode.SLIDER,
config_key="best_price_max_level_gap_count",
config_section="period_settings",
is_peak_price=False,
default_value=1, # DEFAULT_BEST_PRICE_MAX_LEVEL_GAP_COUNT
),
)
# ============================================================================
# PEAK PRICE PERIOD CONFIGURATION OVERRIDES
# ============================================================================
PEAK_PRICE_NUMBER_ENTITIES = (
TibberPricesNumberEntityDescription(
key="peak_price_flex_override",
translation_key="peak_price_flex_override",
name="Peak Price: Flexibility",
icon="mdi:arrow-up-bold-circle",
entity_category=EntityCategory.CONFIG,
entity_registry_enabled_default=False,
native_min_value=-50,
native_max_value=0,
native_step=1,
native_unit_of_measurement=PERCENTAGE,
mode=NumberMode.SLIDER,
config_key="peak_price_flex",
config_section="flexibility_settings",
is_peak_price=True,
default_value=-20, # DEFAULT_PEAK_PRICE_FLEX
),
TibberPricesNumberEntityDescription(
key="peak_price_min_distance_override",
translation_key="peak_price_min_distance_override",
name="Peak Price: Minimum Distance",
icon="mdi:arrow-up-bold-circle",
entity_category=EntityCategory.CONFIG,
entity_registry_enabled_default=False,
native_min_value=0,
native_max_value=50,
native_step=1,
native_unit_of_measurement=PERCENTAGE,
mode=NumberMode.SLIDER,
config_key="peak_price_min_distance_from_avg",
config_section="flexibility_settings",
is_peak_price=True,
default_value=5, # DEFAULT_PEAK_PRICE_MIN_DISTANCE_FROM_AVG
),
TibberPricesNumberEntityDescription(
key="peak_price_min_period_length_override",
translation_key="peak_price_min_period_length_override",
name="Peak Price: Minimum Period Length",
icon="mdi:arrow-up-bold-circle",
entity_category=EntityCategory.CONFIG,
entity_registry_enabled_default=False,
native_min_value=15,
native_max_value=180,
native_step=15,
native_unit_of_measurement="min",
mode=NumberMode.SLIDER,
config_key="peak_price_min_period_length",
config_section="period_settings",
is_peak_price=True,
default_value=30, # DEFAULT_PEAK_PRICE_MIN_PERIOD_LENGTH
),
TibberPricesNumberEntityDescription(
key="peak_price_min_periods_override",
translation_key="peak_price_min_periods_override",
name="Peak Price: Minimum Periods",
icon="mdi:arrow-up-bold-circle",
entity_category=EntityCategory.CONFIG,
entity_registry_enabled_default=False,
native_min_value=1,
native_max_value=10,
native_step=1,
mode=NumberMode.SLIDER,
config_key="min_periods_peak",
config_section="relaxation_and_target_periods",
is_peak_price=True,
default_value=2, # DEFAULT_MIN_PERIODS_PEAK
),
TibberPricesNumberEntityDescription(
key="peak_price_relaxation_attempts_override",
translation_key="peak_price_relaxation_attempts_override",
name="Peak Price: Relaxation Attempts",
icon="mdi:arrow-up-bold-circle",
entity_category=EntityCategory.CONFIG,
entity_registry_enabled_default=False,
native_min_value=1,
native_max_value=12,
native_step=1,
mode=NumberMode.SLIDER,
config_key="relaxation_attempts_peak",
config_section="relaxation_and_target_periods",
is_peak_price=True,
default_value=11, # DEFAULT_RELAXATION_ATTEMPTS_PEAK
),
TibberPricesNumberEntityDescription(
key="peak_price_gap_count_override",
translation_key="peak_price_gap_count_override",
name="Peak Price: Gap Tolerance",
icon="mdi:arrow-up-bold-circle",
entity_category=EntityCategory.CONFIG,
entity_registry_enabled_default=False,
native_min_value=0,
native_max_value=8,
native_step=1,
mode=NumberMode.SLIDER,
config_key="peak_price_max_level_gap_count",
config_section="period_settings",
is_peak_price=True,
default_value=1, # DEFAULT_PEAK_PRICE_MAX_LEVEL_GAP_COUNT
),
)
# All number entity descriptions combined
NUMBER_ENTITY_DESCRIPTIONS = BEST_PRICE_NUMBER_ENTITIES + PEAK_PRICE_NUMBER_ENTITIES

View file

@ -17,11 +17,6 @@ from __future__ import annotations
from typing import TYPE_CHECKING
from custom_components.tibber_prices.const import (
CONF_CURRENCY_DISPLAY_MODE,
DISPLAY_MODE_BASE,
)
from .core import TibberPricesSensor
from .definitions import ENTITY_DESCRIPTIONS
@ -39,22 +34,10 @@ async def async_setup_entry(
"""Set up Tibber Prices sensor based on a config entry."""
coordinator = entry.runtime_data.coordinator
# Get display mode from config
display_mode = entry.options.get(CONF_CURRENCY_DISPLAY_MODE, DISPLAY_MODE_BASE)
# Filter entity descriptions based on display mode
# Skip current_interval_price_base if user configured major display
# (regular current_interval_price already shows major units)
entities_to_create = [
entity_description
for entity_description in ENTITY_DESCRIPTIONS
if not (entity_description.key == "current_interval_price_base" and display_mode == DISPLAY_MODE_BASE)
]
async_add_entities(
TibberPricesSensor(
coordinator=coordinator,
entity_description=entity_description,
)
for entity_description in entities_to_create
for entity_description in ENTITY_DESCRIPTIONS
)

View file

@ -14,56 +14,26 @@ from custom_components.tibber_prices.entity_utils import (
add_description_attributes,
add_icon_color_attribute,
)
from custom_components.tibber_prices.sensor.types import (
DailyStatPriceAttributes,
DailyStatRatingAttributes,
FutureAttributes,
IntervalLevelAttributes,
# Import all types for re-export
IntervalPriceAttributes,
IntervalRatingAttributes,
LifecycleAttributes,
MetadataAttributes,
SensorAttributes,
TimingAttributes,
TrendAttributes,
VolatilityAttributes,
Window24hAttributes,
)
from custom_components.tibber_prices.utils.average import round_to_nearest_quarter_hour
from homeassistant.util import dt as dt_util
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator.core import (
TibberPricesDataUpdateCoordinator,
)
from custom_components.tibber_prices.coordinator.time_service import TibberPricesTimeService
from custom_components.tibber_prices.data import TibberPricesConfigEntry
from homeassistant.core import HomeAssistant
# Import from specialized modules
from .daily_stat import add_statistics_attributes
from .future import add_next_avg_attributes, get_future_prices
from .future import add_next_avg_attributes, add_price_forecast_attributes, get_future_prices
from .interval import add_current_interval_price_attributes
from .lifecycle import build_lifecycle_attributes
from .timing import _is_timing_or_volatility_sensor
from .trend import _add_cached_trend_attributes, _add_timing_or_volatility_attributes
from .volatility import add_volatility_type_attributes, get_prices_for_volatility
from .window_24h import add_average_price_attributes
__all__ = [
"DailyStatPriceAttributes",
"DailyStatRatingAttributes",
"FutureAttributes",
"IntervalLevelAttributes",
"IntervalPriceAttributes",
"IntervalRatingAttributes",
"LifecycleAttributes",
"MetadataAttributes",
# Type exports
"SensorAttributes",
"TimingAttributes",
"TrendAttributes",
"VolatilityAttributes",
"Window24hAttributes",
"add_volatility_type_attributes",
"build_extra_state_attributes",
"build_sensor_attributes",
@ -77,9 +47,7 @@ def build_sensor_attributes(
coordinator: TibberPricesDataUpdateCoordinator,
native_value: Any,
cached_data: dict,
*,
config_entry: TibberPricesConfigEntry,
) -> dict[str, Any] | None:
) -> dict | None:
"""
Build attributes for a sensor based on its key.
@ -90,13 +58,11 @@ def build_sensor_attributes(
coordinator: The data update coordinator
native_value: The current native value of the sensor
cached_data: Dictionary containing cached sensor data
config_entry: Config entry for user preferences
Returns:
Dictionary of attributes or None if no attributes should be added
"""
time = coordinator.time
if not coordinator.data:
return None
@ -129,8 +95,6 @@ def build_sensor_attributes(
coordinator=coordinator,
native_value=native_value,
cached_data=cached_data,
time=time,
config_entry=config_entry,
)
elif key in [
"trailing_price_average",
@ -140,23 +104,9 @@ def build_sensor_attributes(
"leading_price_min",
"leading_price_max",
]:
add_average_price_attributes(
attributes=attributes,
key=key,
coordinator=coordinator,
time=time,
cached_data=cached_data,
config_entry=config_entry,
)
add_average_price_attributes(attributes=attributes, key=key, coordinator=coordinator)
elif key.startswith("next_avg_"):
add_next_avg_attributes(
attributes=attributes,
key=key,
coordinator=coordinator,
time=time,
cached_data=cached_data,
config_entry=config_entry,
)
add_next_avg_attributes(attributes=attributes, key=key, coordinator=coordinator)
elif any(
pattern in key
for pattern in [
@ -177,17 +127,11 @@ def build_sensor_attributes(
attributes=attributes,
key=key,
cached_data=cached_data,
time=time,
config_entry=config_entry,
)
elif key == "data_lifecycle_status":
# Lifecycle sensor uses dedicated builder with calculator
lifecycle_calculator = cached_data.get("lifecycle_calculator")
if lifecycle_calculator:
lifecycle_attrs = build_lifecycle_attributes(coordinator, lifecycle_calculator)
attributes.update(lifecycle_attrs)
elif key == "price_forecast":
add_price_forecast_attributes(attributes=attributes, coordinator=coordinator)
elif _is_timing_or_volatility_sensor(key):
_add_timing_or_volatility_attributes(attributes, key, cached_data, native_value, time=time)
_add_timing_or_volatility_attributes(attributes, key, cached_data, native_value)
# For current_interval_price_level, add the original level as attribute
if key == "current_interval_price_level" and cached_data.get("last_price_level") is not None:
@ -224,8 +168,7 @@ def build_extra_state_attributes( # noqa: PLR0913
*,
config_entry: TibberPricesConfigEntry,
coordinator_data: dict,
sensor_attrs: dict[str, Any] | None = None,
time: TibberPricesTimeService,
sensor_attrs: dict | None = None,
) -> dict[str, Any] | None:
"""
Build extra state attributes for sensors.
@ -243,7 +186,6 @@ def build_extra_state_attributes( # noqa: PLR0913
config_entry: Config entry with options (keyword-only)
coordinator_data: Coordinator data dict (keyword-only)
sensor_attrs: Sensor-specific attributes (keyword-only)
time: TibberPricesTimeService instance (required)
Returns:
Complete attributes dict or None if no data available
@ -255,13 +197,13 @@ def build_extra_state_attributes( # noqa: PLR0913
# Calculate default timestamp: current time rounded to nearest quarter hour
# This ensures all sensors have a consistent reference time for when calculations were made
# Individual sensors can override this if they need a different timestamp
now = time.now()
default_timestamp = time.round_to_nearest_quarter(now)
now = dt_util.now()
default_timestamp = round_to_nearest_quarter_hour(now)
# Special handling for chart_data_export: metadata → descriptions → service data
if entity_key == "chart_data_export":
attributes: dict[str, Any] = {
"timestamp": default_timestamp,
"timestamp": default_timestamp.isoformat(),
}
# Step 1: Add metadata (timestamp + error if present)
@ -290,9 +232,9 @@ def build_extra_state_attributes( # noqa: PLR0913
return attributes if attributes else None
# For all other sensors: standard behavior
# Start with default timestamp (datetime object - HA serializes automatically)
# Start with default timestamp
attributes: dict[str, Any] = {
"timestamp": default_timestamp,
"timestamp": default_timestamp.isoformat(),
}
# Add sensor-specific attributes (may override timestamp)

View file

@ -2,36 +2,24 @@
from __future__ import annotations
from typing import TYPE_CHECKING
from datetime import timedelta
from custom_components.tibber_prices.const import PRICE_RATING_MAPPING
from custom_components.tibber_prices.coordinator.helpers import (
get_intervals_for_day_offsets,
)
from homeassistant.const import PERCENTAGE
if TYPE_CHECKING:
from datetime import datetime
from custom_components.tibber_prices.coordinator.time_service import TibberPricesTimeService
from custom_components.tibber_prices.data import TibberPricesConfigEntry
from .helpers import add_alternate_average_attribute
from homeassistant.util import dt as dt_util
def _get_day_midnight_timestamp(key: str, *, time: TibberPricesTimeService) -> datetime:
"""Get midnight timestamp for a given day sensor key (returns datetime object)."""
# Determine which day based on sensor key
def _get_day_midnight_timestamp(key: str) -> str:
"""Get midnight timestamp for a given day sensor key."""
now = dt_util.now()
local_midnight = dt_util.start_of_local_day(now)
if key.startswith("yesterday") or key == "average_price_yesterday":
day = "yesterday"
local_midnight = local_midnight - timedelta(days=1)
elif key.startswith("tomorrow") or key == "average_price_tomorrow":
day = "tomorrow"
else:
day = "today"
local_midnight = local_midnight + timedelta(days=1)
# Use TimeService to get midnight for that day
local_midnight, _ = time.get_day_boundaries(day)
return local_midnight
return local_midnight.isoformat()
def _get_day_key_from_sensor_key(key: str) -> str:
@ -52,41 +40,26 @@ def _get_day_key_from_sensor_key(key: str) -> str:
return "today"
def _add_fallback_timestamp(
attributes: dict,
key: str,
price_info: dict,
) -> None:
def _add_fallback_timestamp(attributes: dict, key: str, price_info: dict) -> None:
"""
Add fallback timestamp to attributes based on the day in the sensor key.
Args:
attributes: Dictionary to add timestamp to
key: The sensor entity key
price_info: Price info dictionary from coordinator data (flat structure)
price_info: Price info dictionary from coordinator data
"""
day_key = _get_day_key_from_sensor_key(key)
# Use helper to get intervals for this day
# Build minimal coordinator_data structure for helper
coordinator_data = {"priceInfo": price_info}
# Map day key to offset: yesterday=-1, today=0, tomorrow=1
day_offset = {"yesterday": -1, "today": 0, "tomorrow": 1}[day_key]
day_intervals = get_intervals_for_day_offsets(coordinator_data, [day_offset])
# Use first interval's timestamp if available
if day_intervals:
attributes["timestamp"] = day_intervals[0].get("startsAt")
day_data = price_info.get(day_key, [])
if day_data:
attributes["timestamp"] = day_data[0].get("startsAt")
def add_statistics_attributes(
attributes: dict,
key: str,
cached_data: dict,
*,
time: TibberPricesTimeService,
config_entry: TibberPricesConfigEntry,
) -> None:
"""
Add attributes for statistics and rating sensors.
@ -95,15 +68,13 @@ def add_statistics_attributes(
attributes: Dictionary to add attributes to
key: The sensor entity key
cached_data: Dictionary containing cached sensor data
time: TibberPricesTimeService instance (required)
config_entry: Config entry for user preferences
"""
# Data timestamp sensor - shows API fetch time
if key == "data_timestamp":
latest_timestamp = cached_data.get("data_timestamp")
if latest_timestamp:
attributes["timestamp"] = latest_timestamp
attributes["timestamp"] = latest_timestamp.isoformat()
return
# Current interval price rating - add rating attributes
@ -131,17 +102,10 @@ def add_statistics_attributes(
attributes["timestamp"] = extreme_starts_at
return
# Daily average sensors - show midnight to indicate whole day + add alternate value
# Daily average sensors - show midnight to indicate whole day
daily_avg_sensors = {"average_price_today", "average_price_tomorrow"}
if key in daily_avg_sensors:
attributes["timestamp"] = _get_day_midnight_timestamp(key, time=time)
# Add alternate average attribute
add_alternate_average_attribute(
attributes,
cached_data,
key, # base_key = key itself ("average_price_today" or "average_price_tomorrow")
config_entry=config_entry,
)
attributes["timestamp"] = _get_day_midnight_timestamp(key)
return
# Daily aggregated level/rating sensors - show midnight to indicate whole day
@ -154,7 +118,7 @@ def add_statistics_attributes(
"tomorrow_price_rating",
}
if key in daily_aggregated_sensors:
attributes["timestamp"] = _get_day_midnight_timestamp(key, time=time)
attributes["timestamp"] = _get_day_midnight_timestamp(key)
return
# All other statistics sensors - keep default timestamp (when calculation was made)

View file

@ -2,32 +2,25 @@
from __future__ import annotations
from typing import TYPE_CHECKING
from datetime import datetime, timedelta
from typing import TYPE_CHECKING, Any
from custom_components.tibber_prices.const import get_display_unit_factor
from custom_components.tibber_prices.coordinator.helpers import get_intervals_for_day_offsets
from custom_components.tibber_prices.const import MINUTES_PER_INTERVAL
from homeassistant.util import dt as dt_util
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator.core import (
TibberPricesDataUpdateCoordinator,
)
from custom_components.tibber_prices.coordinator.time_service import TibberPricesTimeService
from custom_components.tibber_prices.data import TibberPricesConfigEntry
from .helpers import add_alternate_average_attribute
# Constants
MAX_FORECAST_INTERVALS = 8 # Show up to 8 future intervals (2 hours with 15-min intervals)
def add_next_avg_attributes( # noqa: PLR0913
def add_next_avg_attributes(
attributes: dict,
key: str,
coordinator: TibberPricesDataUpdateCoordinator,
*,
time: TibberPricesTimeService,
cached_data: dict | None = None,
config_entry: TibberPricesConfigEntry | None = None,
) -> None:
"""
Add attributes for next N hours average price sensors.
@ -36,31 +29,38 @@ def add_next_avg_attributes( # noqa: PLR0913
attributes: Dictionary to add attributes to
key: The sensor entity key
coordinator: The data update coordinator
time: TibberPricesTimeService instance (required)
cached_data: Optional cached data dictionary for median values
config_entry: Optional config entry for user preferences
"""
now = dt_util.now()
# Extract hours from sensor key (e.g., "next_avg_3h" -> 3)
try:
hours = int(key.split("_")[-1].replace("h", ""))
hours = int(key.replace("next_avg_", "").replace("h", ""))
except (ValueError, AttributeError):
return
# Use TimeService to get the N-hour window starting from next interval
next_interval_start, window_end = time.get_next_n_hours_window(hours)
# Get next interval start time (this is where the calculation begins)
next_interval_start = now + timedelta(minutes=MINUTES_PER_INTERVAL)
# Get all intervals (yesterday, today, tomorrow) via helper
all_prices = get_intervals_for_day_offsets(coordinator.data, [-1, 0, 1])
# Calculate the end of the time window
window_end = next_interval_start + timedelta(hours=hours)
# Get all price intervals
price_info = coordinator.data.get("priceInfo", {})
today_prices = price_info.get("today", [])
tomorrow_prices = price_info.get("tomorrow", [])
all_prices = today_prices + tomorrow_prices
if not all_prices:
return
# Find all intervals in the window
intervals_in_window = []
for price_data in all_prices:
starts_at = time.get_interval_time(price_data)
starts_at = dt_util.parse_datetime(price_data["startsAt"])
if starts_at is None:
continue
starts_at = dt_util.as_local(starts_at)
if next_interval_start <= starts_at < window_end:
intervals_in_window.append(price_data)
@ -70,92 +70,151 @@ def add_next_avg_attributes( # noqa: PLR0913
attributes["interval_count"] = len(intervals_in_window)
attributes["hours"] = hours
# Add alternate average attribute if available in cached_data
if cached_data and config_entry:
base_key = f"next_avg_{hours}h"
add_alternate_average_attribute(
attributes,
cached_data,
base_key,
config_entry=config_entry,
)
def add_price_forecast_attributes(
attributes: dict,
coordinator: TibberPricesDataUpdateCoordinator,
) -> None:
"""
Add forecast attributes for the price forecast sensor.
Args:
attributes: Dictionary to add attributes to
coordinator: The data update coordinator
"""
future_prices = get_future_prices(coordinator, max_intervals=MAX_FORECAST_INTERVALS)
if not future_prices:
attributes["intervals"] = []
attributes["intervals_by_hour"] = []
attributes["data_available"] = False
return
# Add timestamp attribute (first future interval)
if future_prices:
attributes["timestamp"] = future_prices[0]["interval_start"]
attributes["intervals"] = future_prices
attributes["data_available"] = True
# Group by hour for easier consumption in dashboards
hours: dict[str, Any] = {}
for interval in future_prices:
starts_at = datetime.fromisoformat(interval["interval_start"])
hour_key = starts_at.strftime("%Y-%m-%d %H")
if hour_key not in hours:
hours[hour_key] = {
"hour": starts_at.hour,
"day": interval["day"],
"date": starts_at.date().isoformat(),
"intervals": [],
"min_price": None,
"max_price": None,
"avg_price": 0,
"avg_rating": None, # Initialize rating tracking
"ratings_available": False, # Track if any ratings are available
}
# Create interval data with both price and rating info
interval_data = {
"minute": starts_at.minute,
"price": interval["price"],
"price_minor": interval["price_minor"],
"level": interval["level"], # Price level from priceInfo
"time": starts_at.strftime("%H:%M"),
}
# Add rating data if available
if interval["rating"] is not None:
interval_data["rating"] = interval["rating"]
interval_data["rating_level"] = interval["rating_level"]
hours[hour_key]["ratings_available"] = True
hours[hour_key]["intervals"].append(interval_data)
# Track min/max/avg for the hour
price = interval["price"]
if hours[hour_key]["min_price"] is None or price < hours[hour_key]["min_price"]:
hours[hour_key]["min_price"] = price
if hours[hour_key]["max_price"] is None or price > hours[hour_key]["max_price"]:
hours[hour_key]["max_price"] = price
# Calculate averages
for hour_data in hours.values():
prices = [interval["price"] for interval in hour_data["intervals"]]
if prices:
hour_data["avg_price"] = sum(prices) / len(prices)
hour_data["min_price"] = hour_data["min_price"]
hour_data["max_price"] = hour_data["max_price"]
# Calculate average rating if ratings are available
if hour_data["ratings_available"]:
ratings = [interval.get("rating") for interval in hour_data["intervals"] if "rating" in interval]
if ratings:
hour_data["avg_rating"] = sum(ratings) / len(ratings)
# Convert to list sorted by hour
attributes["intervals_by_hour"] = [hour_data for _, hour_data in sorted(hours.items())]
def get_future_prices(
coordinator: TibberPricesDataUpdateCoordinator,
max_intervals: int | None = None,
*,
time: TibberPricesTimeService,
config_entry: TibberPricesConfigEntry,
) -> list[dict] | None:
"""
Get future price data for multiple upcoming intervals.
Args:
coordinator: The data update coordinator.
max_intervals: Maximum number of future intervals to return.
time: TibberPricesTimeService instance (required).
config_entry: Config entry to get display unit configuration.
coordinator: The data update coordinator
max_intervals: Maximum number of future intervals to return
Returns:
List of upcoming price intervals with timestamps and prices.
List of upcoming price intervals with timestamps and prices
"""
if not coordinator.data:
return None
# Get all intervals (yesterday, today, tomorrow) via helper
all_prices = get_intervals_for_day_offsets(coordinator.data, [-1, 0, 1])
price_info = coordinator.data.get("priceInfo", {})
today_prices = price_info.get("today", [])
tomorrow_prices = price_info.get("tomorrow", [])
all_prices = today_prices + tomorrow_prices
if not all_prices:
return None
now = dt_util.now()
# Initialize the result list
future_prices = []
# Track the maximum intervals to return
intervals_to_return = MAX_FORECAST_INTERVALS if max_intervals is None else max_intervals
# Get current date for day key determination
now = time.now()
today_date = now.date()
tomorrow_date = time.get_local_date(offset_days=1)
for day_key in ["today", "tomorrow"]:
for price_data in price_info.get(day_key, []):
starts_at = dt_util.parse_datetime(price_data["startsAt"])
if starts_at is None:
continue
for price_data in all_prices:
starts_at = time.get_interval_time(price_data)
if starts_at is None:
continue
starts_at = dt_util.as_local(starts_at)
interval_end = starts_at + timedelta(minutes=MINUTES_PER_INTERVAL)
interval_end = starts_at + time.get_interval_duration()
# Use TimeService to check if interval is in future
if time.is_in_future(starts_at):
# Determine which day this interval belongs to
interval_date = starts_at.date()
if interval_date == today_date:
day_key = "today"
elif interval_date == tomorrow_date:
day_key = "tomorrow"
else:
day_key = "unknown"
# Convert to display currency unit based on configuration
price_major = float(price_data["total"])
factor = get_display_unit_factor(config_entry)
price_display = round(price_major * factor, 2)
future_prices.append(
{
"interval_start": starts_at,
"interval_end": interval_end,
"price": price_major,
"price_minor": price_display,
"level": price_data.get("level", "NORMAL"),
"rating": price_data.get("difference", None),
"rating_level": price_data.get("rating_level"),
"day": day_key,
}
)
if starts_at > now:
future_prices.append(
{
"interval_start": starts_at.isoformat(),
"interval_end": interval_end.isoformat(),
"price": float(price_data["total"]),
"price_minor": round(float(price_data["total"]) * 100, 2),
"level": price_data.get("level", "NORMAL"),
"rating": price_data.get("difference", None),
"rating_level": price_data.get("rating_level"),
"day": day_key,
}
)
# Sort by start time
future_prices.sort(key=lambda x: x["interval_start"])

View file

@ -1,41 +0,0 @@
"""Helper functions for sensor attributes."""
from __future__ import annotations
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from custom_components.tibber_prices.data import TibberPricesConfigEntry
def add_alternate_average_attribute(
attributes: dict,
cached_data: dict,
base_key: str,
*,
config_entry: TibberPricesConfigEntry, # noqa: ARG001
) -> None:
"""
Add both average values (mean and median) as attributes.
This ensures automations work consistently regardless of which value
is displayed in the state. Both values are always available as attributes.
Note: To avoid duplicate recording, the value used as state should be
excluded from recorder via dynamic _unrecorded_attributes in sensor core.
Args:
attributes: Dictionary to add attribute to
cached_data: Cached calculation data containing mean/median values
base_key: Base key for cached values (e.g., "average_price_today", "rolling_hour_0")
config_entry: Config entry for user preferences (used to determine which value is in state)
"""
# Always add both mean and median values as attributes
mean_value = cached_data.get(f"{base_key}_mean")
if mean_value is not None:
attributes["price_mean"] = mean_value
median_value = cached_data.get(f"{base_key}_median")
if median_value is not None:
attributes["price_median"] = median_value

View file

@ -6,98 +6,28 @@ from datetime import timedelta
from typing import TYPE_CHECKING, Any
from custom_components.tibber_prices.const import (
MINUTES_PER_INTERVAL,
PRICE_LEVEL_MAPPING,
PRICE_RATING_MAPPING,
)
from custom_components.tibber_prices.entity_utils import add_icon_color_attribute
from custom_components.tibber_prices.utils.price import find_price_data_for_interval
from homeassistant.util import dt as dt_util
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator.core import (
TibberPricesDataUpdateCoordinator,
)
from custom_components.tibber_prices.coordinator.time_service import TibberPricesTimeService
from custom_components.tibber_prices.data import TibberPricesConfigEntry
from .helpers import add_alternate_average_attribute
from .metadata import get_current_interval_data
def _get_interval_data_for_attributes(
key: str,
coordinator: TibberPricesDataUpdateCoordinator,
attributes: dict,
*,
time: TibberPricesTimeService,
) -> dict | None:
"""
Get interval data and set timestamp based on sensor type.
Refactored to reduce branch complexity in main function.
Args:
key: The sensor entity key
coordinator: The data update coordinator
attributes: Attributes dict to update with timestamp if needed
time: TibberPricesTimeService instance
Returns:
Interval data if found, None otherwise
"""
now = time.now()
# Current/next price sensors - override timestamp with interval's startsAt
next_sensors = ["next_interval_price", "next_interval_price_level", "next_interval_price_rating"]
prev_sensors = ["previous_interval_price", "previous_interval_price_level", "previous_interval_price_rating"]
next_hour = ["next_hour_average_price", "next_hour_price_level", "next_hour_price_rating"]
curr_interval = ["current_interval_price", "current_interval_price_base"]
curr_hour = ["current_hour_average_price", "current_hour_price_level", "current_hour_price_rating"]
if key in next_sensors:
target_time = time.get_next_interval_start()
interval_data = find_price_data_for_interval(coordinator.data, target_time, time=time)
if interval_data:
attributes["timestamp"] = interval_data["startsAt"]
return interval_data
if key in prev_sensors:
target_time = time.get_interval_offset_time(-1)
interval_data = find_price_data_for_interval(coordinator.data, target_time, time=time)
if interval_data:
attributes["timestamp"] = interval_data["startsAt"]
return interval_data
if key in next_hour:
target_time = now + timedelta(hours=1)
interval_data = find_price_data_for_interval(coordinator.data, target_time, time=time)
if interval_data:
attributes["timestamp"] = interval_data["startsAt"]
return interval_data
# Current interval sensors (both variants)
if key in curr_interval:
interval_data = get_current_interval_data(coordinator, time=time)
if interval_data and "startsAt" in interval_data:
attributes["timestamp"] = interval_data["startsAt"]
return interval_data
# Current hour sensors - keep default timestamp
if key in curr_hour:
return get_current_interval_data(coordinator, time=time)
return None
def add_current_interval_price_attributes( # noqa: PLR0913
def add_current_interval_price_attributes(
attributes: dict,
key: str,
coordinator: TibberPricesDataUpdateCoordinator,
native_value: Any,
cached_data: dict,
*,
time: TibberPricesTimeService,
config_entry: TibberPricesConfigEntry,
) -> None:
"""
Add attributes for current interval price sensors.
@ -108,20 +38,65 @@ def add_current_interval_price_attributes( # noqa: PLR0913
coordinator: The data update coordinator
native_value: The current native value of the sensor
cached_data: Dictionary containing cached sensor data
time: TibberPricesTimeService instance (required)
config_entry: Config entry for user preferences
"""
# Get interval data and handle timestamp overrides
interval_data = _get_interval_data_for_attributes(key, coordinator, attributes, time=time)
price_info = coordinator.data.get("priceInfo", {}) if coordinator.data else {}
now = dt_util.now()
# Determine which interval to use based on sensor type
next_interval_sensors = [
"next_interval_price",
"next_interval_price_level",
"next_interval_price_rating",
]
previous_interval_sensors = [
"previous_interval_price",
"previous_interval_price_level",
"previous_interval_price_rating",
]
next_hour_sensors = [
"next_hour_average_price",
"next_hour_price_level",
"next_hour_price_rating",
]
current_hour_sensors = [
"current_hour_average_price",
"current_hour_price_level",
"current_hour_price_rating",
]
# Set interval data based on sensor type
# For sensors showing data from OTHER intervals (next/previous), override timestamp with that interval's startsAt
# For current interval sensors, keep the default platform timestamp (calculation time)
interval_data = None
if key in next_interval_sensors:
target_time = now + timedelta(minutes=MINUTES_PER_INTERVAL)
interval_data = find_price_data_for_interval(price_info, target_time)
# Override timestamp with the NEXT interval's startsAt (when that interval starts)
if interval_data:
attributes["timestamp"] = interval_data["startsAt"]
elif key in previous_interval_sensors:
target_time = now - timedelta(minutes=MINUTES_PER_INTERVAL)
interval_data = find_price_data_for_interval(price_info, target_time)
# Override timestamp with the PREVIOUS interval's startsAt
if interval_data:
attributes["timestamp"] = interval_data["startsAt"]
elif key in next_hour_sensors:
target_time = now + timedelta(hours=1)
interval_data = find_price_data_for_interval(price_info, target_time)
# Override timestamp with the center of the next rolling hour window
if interval_data:
attributes["timestamp"] = interval_data["startsAt"]
elif key in current_hour_sensors:
current_interval_data = get_current_interval_data(coordinator)
# Keep default timestamp (when calculation was made) for current hour sensors
else:
current_interval_data = get_current_interval_data(coordinator)
interval_data = current_interval_data # Use current_interval_data as interval_data for current_interval_price
# Keep default timestamp (current calculation time) for current interval sensors
# Add icon_color for price sensors (based on their price level)
if key in [
"current_interval_price",
"current_interval_price_base",
"next_interval_price",
"previous_interval_price",
]:
if key in ["current_interval_price", "next_interval_price", "previous_interval_price"]:
# For interval-based price sensors, get level from interval_data
if interval_data and "level" in interval_data:
level = interval_data["level"]
@ -132,15 +107,6 @@ def add_current_interval_price_attributes( # noqa: PLR0913
if level:
add_icon_color_attribute(attributes, key="price_level", state_value=level)
# Add alternate average attribute for rolling hour average price sensors
base_key = "rolling_hour_0" if key == "current_hour_average_price" else "rolling_hour_1"
add_alternate_average_attribute(
attributes,
cached_data,
base_key,
config_entry=config_entry,
)
# Add price level attributes for all level sensors
add_level_attributes_for_sensor(
attributes=attributes,
@ -148,7 +114,6 @@ def add_current_interval_price_attributes( # noqa: PLR0913
interval_data=interval_data,
coordinator=coordinator,
native_value=native_value,
time=time,
)
# Add price rating attributes for all rating sensors
@ -158,18 +123,15 @@ def add_current_interval_price_attributes( # noqa: PLR0913
interval_data=interval_data,
coordinator=coordinator,
native_value=native_value,
time=time,
)
def add_level_attributes_for_sensor( # noqa: PLR0913
def add_level_attributes_for_sensor(
attributes: dict,
key: str,
interval_data: dict | None,
coordinator: TibberPricesDataUpdateCoordinator,
native_value: Any,
*,
time: TibberPricesTimeService,
) -> None:
"""
Add price level attributes based on sensor type.
@ -180,7 +142,6 @@ def add_level_attributes_for_sensor( # noqa: PLR0913
interval_data: Interval data for next/previous sensors
coordinator: The data update coordinator
native_value: The current native value of the sensor
time: TibberPricesTimeService instance (required)
"""
# For interval-based level sensors (next/previous), use interval data
@ -194,7 +155,7 @@ def add_level_attributes_for_sensor( # noqa: PLR0913
add_price_level_attributes(attributes, level_value.upper())
# For current price level sensor
elif key == "current_interval_price_level":
current_interval_data = get_current_interval_data(coordinator, time=time)
current_interval_data = get_current_interval_data(coordinator)
if current_interval_data and "level" in current_interval_data:
add_price_level_attributes(attributes, current_interval_data["level"])
@ -216,14 +177,12 @@ def add_price_level_attributes(attributes: dict, level: str) -> None:
add_icon_color_attribute(attributes, key="price_level", state_value=level)
def add_rating_attributes_for_sensor( # noqa: PLR0913
def add_rating_attributes_for_sensor(
attributes: dict,
key: str,
interval_data: dict | None,
coordinator: TibberPricesDataUpdateCoordinator,
native_value: Any,
*,
time: TibberPricesTimeService,
) -> None:
"""
Add price rating attributes based on sensor type.
@ -234,7 +193,6 @@ def add_rating_attributes_for_sensor( # noqa: PLR0913
interval_data: Interval data for next/previous sensors
coordinator: The data update coordinator
native_value: The current native value of the sensor
time: TibberPricesTimeService instance (required)
"""
# For interval-based rating sensors (next/previous), use interval data
@ -248,7 +206,7 @@ def add_rating_attributes_for_sensor( # noqa: PLR0913
add_price_rating_attributes(attributes, rating_value.upper())
# For current price rating sensor
elif key == "current_interval_price_rating":
current_interval_data = get_current_interval_data(coordinator, time=time)
current_interval_data = get_current_interval_data(coordinator)
if current_interval_data and "rating_level" in current_interval_data:
add_price_rating_attributes(attributes, current_interval_data["rating_level"])

View file

@ -1,83 +0,0 @@
"""
Attribute builders for lifecycle diagnostic sensor.
This sensor uses event-based updates with state-change filtering to minimize
recorder entries. Only attributes that are relevant to the lifecycle STATE
are included here - attributes that change independently of state belong
in a separate sensor or diagnostics.
Included attributes (update only on state change):
- tomorrow_available: Whether tomorrow's price data is available
- next_api_poll: When the next API poll will occur (builds user trust)
- updates_today: Number of API calls made today
- last_turnover: When the last midnight turnover occurred
- last_error: Details of the last error (if any)
Pool statistics (sensor_intervals_count, cache_fill_percent, etc.) are
intentionally NOT included here because they change independently of
the lifecycle state. With state-change filtering, these would become
stale. Pool statistics are available via diagnostics or could be
exposed as a separate sensor if needed.
"""
from __future__ import annotations
from typing import TYPE_CHECKING, Any
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator.core import (
TibberPricesDataUpdateCoordinator,
)
from custom_components.tibber_prices.sensor.calculators.lifecycle import (
TibberPricesLifecycleCalculator,
)
def build_lifecycle_attributes(
coordinator: TibberPricesDataUpdateCoordinator,
lifecycle_calculator: TibberPricesLifecycleCalculator,
) -> dict[str, Any]:
"""
Build attributes for data_lifecycle_status sensor.
Event-based updates with state-change filtering - attributes only update
when the lifecycle STATE changes (freshcached, cachedturnover_pending, etc.).
Only includes attributes that are directly relevant to the lifecycle state.
Pool statistics are intentionally excluded to avoid stale data.
Returns:
Dict with lifecycle attributes
"""
attributes: dict[str, Any] = {}
# === Tomorrow Data Status ===
# Critical for understanding lifecycle state transitions
attributes["tomorrow_available"] = lifecycle_calculator.has_tomorrow_data()
# === Next API Poll Time ===
# Builds user trust: shows when the integration will check for tomorrow data
# - Before 13:00: Shows today 13:00 (when tomorrow-search begins)
# - After 13:00 without tomorrow data: Shows next Timer #1 execution (active polling)
# - After 13:00 with tomorrow data: Shows tomorrow 13:00 (predictive)
next_poll = lifecycle_calculator.get_next_api_poll_time()
if next_poll:
attributes["next_api_poll"] = next_poll.isoformat()
# === Update Statistics ===
# Shows API activity - resets at midnight with turnover
api_calls = lifecycle_calculator.get_api_calls_today()
attributes["updates_today"] = api_calls
# === Midnight Turnover Info ===
# When was the last successful data rotation
if coordinator._midnight_handler.last_turnover_time: # noqa: SLF001
attributes["last_turnover"] = coordinator._midnight_handler.last_turnover_time.isoformat() # noqa: SLF001
# === Error Status ===
# Present only when there's an active error
if coordinator.last_exception:
attributes["last_error"] = str(coordinator.last_exception)
return attributes

View file

@ -5,33 +5,31 @@ from __future__ import annotations
from typing import TYPE_CHECKING
from custom_components.tibber_prices.utils.price import find_price_data_for_interval
from homeassistant.util import dt as dt_util
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator.core import (
TibberPricesDataUpdateCoordinator,
)
from custom_components.tibber_prices.coordinator.time_service import TibberPricesTimeService
def get_current_interval_data(
coordinator: TibberPricesDataUpdateCoordinator,
*,
time: TibberPricesTimeService,
) -> dict | None:
"""
Get current interval's price data.
Get the current price interval data.
Args:
coordinator: The data update coordinator
time: TibberPricesTimeService instance (required)
Returns:
Current interval data or None if not found
Current interval data dict, or None if unavailable
"""
if not coordinator.data:
return None
now = time.now()
price_info = coordinator.data.get("priceInfo", {})
now = dt_util.now()
return find_price_data_for_interval(coordinator.data, now, time=time)
return find_price_data_for_interval(price_info, now)

View file

@ -2,26 +2,10 @@
from __future__ import annotations
from typing import TYPE_CHECKING, Any
from typing import Any
from custom_components.tibber_prices.entity_utils import add_icon_color_attribute
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator.time_service import TibberPricesTimeService
# Timer #3 triggers every 30 seconds
TIMER_30_SEC_BOUNDARY = 30
def _hours_to_minutes(state_value: Any) -> int | None:
"""Convert hour-based state back to rounded minutes for attributes."""
if state_value is None:
return None
try:
return round(float(state_value) * 60)
except (TypeError, ValueError):
return None
from homeassistant.util import dt as dt_util
def _is_timing_or_volatility_sensor(key: str) -> bool:
@ -45,27 +29,24 @@ def add_period_timing_attributes(
attributes: dict,
key: str,
state_value: Any = None,
*,
time: TibberPricesTimeService,
) -> None:
"""
Add timestamp and icon_color attributes for best_price/peak_price timing sensors.
The timestamp indicates when the sensor value was calculated:
- Quarter-hour sensors (end_time, next_start_time): Rounded to 15-min boundary (:00, :15, :30, :45)
- 30-second update sensors (remaining_minutes, progress, next_in_minutes): Current time with seconds
- Quarter-hour sensors (end_time, next_start_time): Timestamp of current 15-min interval
- Minute-update sensors (remaining_minutes, progress, next_in_minutes): Current minute with :00 seconds
Args:
attributes: Dictionary to add attributes to
key: The sensor entity key (e.g., "best_price_end_time")
state_value: Current sensor value for icon_color calculation
time: TibberPricesTimeService instance (required)
"""
# Determine if this is a quarter-hour or 30-second update sensor
# Determine if this is a quarter-hour or minute-update sensor
is_quarter_hour_sensor = key.endswith(("_end_time", "_next_start_time"))
now = time.now()
now = dt_util.now()
if is_quarter_hour_sensor:
# Quarter-hour sensors: Use timestamp of current 15-minute interval
@ -73,23 +54,11 @@ def add_period_timing_attributes(
minute = (now.minute // 15) * 15
timestamp = now.replace(minute=minute, second=0, microsecond=0)
else:
# 30-second update sensors: Round to nearest 30-second boundary (:00 or :30)
# Timer triggers at :00 and :30, so round current time to these boundaries
second = 0 if now.second < TIMER_30_SEC_BOUNDARY else TIMER_30_SEC_BOUNDARY
timestamp = now.replace(second=second, microsecond=0)
# Minute-update sensors: Use current minute with :00 seconds
# This ensures clean timestamps despite timer fluctuations
timestamp = now.replace(second=0, microsecond=0)
attributes["timestamp"] = timestamp
# Add minute-precision attributes for hour-based states to keep automation-friendly values
minute_value = _hours_to_minutes(state_value)
if minute_value is not None:
if key.endswith("period_duration"):
attributes["period_duration_minutes"] = minute_value
elif key.endswith("remaining_minutes"):
attributes["remaining_minutes"] = minute_value
elif key.endswith("next_in_minutes"):
attributes["next_in_minutes"] = minute_value
attributes["timestamp"] = timestamp.isoformat()
# Add icon_color for dynamic styling
add_icon_color_attribute(attributes, key=key, state_value=state_value)

View file

@ -2,10 +2,7 @@
from __future__ import annotations
from typing import TYPE_CHECKING, Any
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator.time_service import TibberPricesTimeService
from typing import Any
from .timing import add_period_timing_attributes
from .volatility import add_volatility_attributes
@ -16,14 +13,12 @@ def _add_timing_or_volatility_attributes(
key: str,
cached_data: dict,
native_value: Any = None,
*,
time: TibberPricesTimeService,
) -> None:
"""Add attributes for timing or volatility sensors."""
if key.endswith("_volatility"):
add_volatility_attributes(attributes=attributes, cached_data=cached_data, time=time)
add_volatility_attributes(attributes=attributes, cached_data=cached_data)
else:
add_period_timing_attributes(attributes=attributes, key=key, state_value=native_value, time=time)
add_period_timing_attributes(attributes=attributes, key=key, state_value=native_value)
def _add_cached_trend_attributes(attributes: dict, key: str, cached_data: dict) -> None:

View file

@ -3,20 +3,14 @@
from __future__ import annotations
from datetime import timedelta
from typing import TYPE_CHECKING
from custom_components.tibber_prices.coordinator.helpers import get_intervals_for_day_offsets
from custom_components.tibber_prices.utils.price import calculate_volatility_level
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator.time_service import TibberPricesTimeService
from homeassistant.util import dt as dt_util
def add_volatility_attributes(
attributes: dict,
cached_data: dict,
*,
time: TibberPricesTimeService, # noqa: ARG001
) -> None:
"""
Add attributes for volatility sensors.
@ -24,7 +18,6 @@ def add_volatility_attributes(
Args:
attributes: Dictionary to add attributes to
cached_data: Dictionary containing cached sensor data
time: TibberPricesTimeService instance (required)
"""
if cached_data.get("volatility_attributes"):
@ -33,67 +26,49 @@ def add_volatility_attributes(
def get_prices_for_volatility(
volatility_type: str,
coordinator_data: dict,
*,
time: TibberPricesTimeService,
price_info: dict,
) -> list[float]:
"""
Get price list for volatility calculation based on type.
Args:
volatility_type: One of "today", "tomorrow", "next_24h", "today_tomorrow"
coordinator_data: Coordinator data dict
time: TibberPricesTimeService instance (required)
price_info: Price information dictionary from coordinator data
Returns:
List of prices to analyze
"""
# Get all intervals (yesterday, today, tomorrow) via helper
all_intervals = get_intervals_for_day_offsets(coordinator_data, [-1, 0, 1])
if volatility_type == "today":
# Filter for today's intervals
today_date = time.now().date()
return [
float(p["total"])
for p in all_intervals
if "total" in p and p.get("startsAt") and p["startsAt"].date() == today_date
]
return [float(p["total"]) for p in price_info.get("today", []) if "total" in p]
if volatility_type == "tomorrow":
# Filter for tomorrow's intervals
tomorrow_date = (time.now() + timedelta(days=1)).date()
return [
float(p["total"])
for p in all_intervals
if "total" in p and p.get("startsAt") and p["startsAt"].date() == tomorrow_date
]
return [float(p["total"]) for p in price_info.get("tomorrow", []) if "total" in p]
if volatility_type == "next_24h":
# Rolling 24h from now
now = time.now()
now = dt_util.now()
end_time = now + timedelta(hours=24)
prices = []
for price_data in all_intervals:
starts_at = price_data.get("startsAt") # Already datetime in local timezone
if starts_at is None:
continue
for day_key in ["today", "tomorrow"]:
for price_data in price_info.get(day_key, []):
starts_at = dt_util.parse_datetime(price_data.get("startsAt"))
if starts_at is None:
continue
starts_at = dt_util.as_local(starts_at)
if time.is_in_future(starts_at) and starts_at < end_time and "total" in price_data:
prices.append(float(price_data["total"]))
if now <= starts_at < end_time and "total" in price_data:
prices.append(float(price_data["total"]))
return prices
if volatility_type == "today_tomorrow":
# Combined today + tomorrow
today_date = time.now().date()
tomorrow_date = (time.now() + timedelta(days=1)).date()
prices = []
for price_data in all_intervals:
starts_at = price_data.get("startsAt")
if starts_at and starts_at.date() in [today_date, tomorrow_date] and "total" in price_data:
prices.append(float(price_data["total"]))
for day_key in ["today", "tomorrow"]:
for price_data in price_info.get(day_key, []):
if "total" in price_data:
prices.append(float(price_data["total"]))
return prices
return []
@ -102,10 +77,8 @@ def get_prices_for_volatility(
def add_volatility_type_attributes(
volatility_attributes: dict,
volatility_type: str,
coordinator_data: dict,
price_info: dict,
thresholds: dict,
*,
time: TibberPricesTimeService,
) -> None:
"""
Add type-specific attributes for volatility sensors.
@ -113,54 +86,43 @@ def add_volatility_type_attributes(
Args:
volatility_attributes: Dictionary to add type-specific attributes to
volatility_type: Type of volatility calculation
coordinator_data: Coordinator data dict
price_info: Price information dictionary from coordinator data
thresholds: Volatility thresholds configuration
time: TibberPricesTimeService instance (required)
"""
# Get all intervals (yesterday, today, tomorrow) via helper
all_intervals = get_intervals_for_day_offsets(coordinator_data, [-1, 0, 1])
now = time.now()
today_date = now.date()
tomorrow_date = (now + timedelta(days=1)).date()
# Add timestamp for calendar day volatility sensors (midnight of the day)
if volatility_type == "today":
today_data = [p for p in all_intervals if p.get("startsAt") and p["startsAt"].date() == today_date]
today_data = price_info.get("today", [])
if today_data:
volatility_attributes["timestamp"] = today_data[0].get("startsAt")
elif volatility_type == "tomorrow":
tomorrow_data = [p for p in all_intervals if p.get("startsAt") and p["startsAt"].date() == tomorrow_date]
tomorrow_data = price_info.get("tomorrow", [])
if tomorrow_data:
volatility_attributes["timestamp"] = tomorrow_data[0].get("startsAt")
elif volatility_type == "today_tomorrow":
# For combined today+tomorrow, use today's midnight
today_data = [p for p in all_intervals if p.get("startsAt") and p["startsAt"].date() == today_date]
today_data = price_info.get("today", [])
if today_data:
volatility_attributes["timestamp"] = today_data[0].get("startsAt")
# Add breakdown for today vs tomorrow
today_prices = [
float(p["total"])
for p in all_intervals
if "total" in p and p.get("startsAt") and p["startsAt"].date() == today_date
]
tomorrow_prices = [
float(p["total"])
for p in all_intervals
if "total" in p and p.get("startsAt") and p["startsAt"].date() == tomorrow_date
]
today_prices = [float(p["total"]) for p in price_info.get("today", []) if "total" in p]
tomorrow_prices = [float(p["total"]) for p in price_info.get("tomorrow", []) if "total" in p]
if today_prices:
today_vol = calculate_volatility_level(today_prices, **thresholds)
today_spread = (max(today_prices) - min(today_prices)) * 100
volatility_attributes["today_spread"] = round(today_spread, 2)
volatility_attributes["today_volatility"] = today_vol
volatility_attributes["interval_count_today"] = len(today_prices)
if tomorrow_prices:
tomorrow_vol = calculate_volatility_level(tomorrow_prices, **thresholds)
tomorrow_spread = (max(tomorrow_prices) - min(tomorrow_prices)) * 100
volatility_attributes["tomorrow_spread"] = round(tomorrow_spread, 2)
volatility_attributes["tomorrow_volatility"] = tomorrow_vol
volatility_attributes["interval_count_tomorrow"] = len(tomorrow_prices)
elif volatility_type == "next_24h":
# Add time window info
now = time.now()
volatility_attributes["timestamp"] = now
now = dt_util.now()
volatility_attributes["timestamp"] = now.isoformat()

View file

@ -2,18 +2,15 @@
from __future__ import annotations
from datetime import timedelta
from typing import TYPE_CHECKING
from custom_components.tibber_prices.coordinator.helpers import get_intervals_for_day_offsets
from homeassistant.util import dt as dt_util
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator.core import (
TibberPricesDataUpdateCoordinator,
)
from custom_components.tibber_prices.coordinator.time_service import TibberPricesTimeService
from custom_components.tibber_prices.data import TibberPricesConfigEntry
from .helpers import add_alternate_average_attribute
def _update_extreme_interval(extreme_interval: dict | None, price_data: dict, key: str) -> dict:
@ -43,14 +40,10 @@ def _update_extreme_interval(extreme_interval: dict | None, price_data: dict, ke
return price_data if is_new_extreme else extreme_interval
def add_average_price_attributes( # noqa: PLR0913
def add_average_price_attributes(
attributes: dict,
key: str,
coordinator: TibberPricesDataUpdateCoordinator,
*,
time: TibberPricesTimeService,
cached_data: dict | None = None,
config_entry: TibberPricesConfigEntry | None = None,
) -> None:
"""
Add attributes for trailing and leading average/min/max price sensors.
@ -59,25 +52,30 @@ def add_average_price_attributes( # noqa: PLR0913
attributes: Dictionary to add attributes to
key: The sensor entity key
coordinator: The data update coordinator
time: TibberPricesTimeService instance (required)
cached_data: Optional cached data dictionary for median values
config_entry: Optional config entry for user preferences
"""
now = dt_util.now()
# Determine if this is trailing or leading
is_trailing = "trailing" in key
# Get all intervals (yesterday, today, tomorrow) via helper
all_prices = get_intervals_for_day_offsets(coordinator.data, [-1, 0, 1])
# Get all price intervals
price_info = coordinator.data.get("priceInfo", {})
yesterday_prices = price_info.get("yesterday", [])
today_prices = price_info.get("today", [])
tomorrow_prices = price_info.get("tomorrow", [])
all_prices = yesterday_prices + today_prices + tomorrow_prices
if not all_prices:
return
# Calculate the time window using TimeService
# Calculate the time window
if is_trailing:
window_start, window_end = time.get_trailing_window(hours=24)
window_start = now - timedelta(hours=24)
window_end = now
else:
window_start, window_end = time.get_leading_window(hours=24)
window_start = now
window_end = now + timedelta(hours=24)
# Find all intervals in the window
intervals_in_window = []
@ -85,9 +83,10 @@ def add_average_price_attributes( # noqa: PLR0913
is_min_max_sensor = "min" in key or "max" in key
for price_data in all_prices:
starts_at = time.get_interval_time(price_data)
starts_at = dt_util.parse_datetime(price_data["startsAt"])
if starts_at is None:
continue
starts_at = dt_util.as_local(starts_at)
if window_start <= starts_at < window_end:
intervals_in_window.append(price_data)
@ -105,13 +104,3 @@ def add_average_price_attributes( # noqa: PLR0913
attributes["timestamp"] = intervals_in_window[0].get("startsAt")
attributes["interval_count"] = len(intervals_in_window)
# Add alternate average attribute for average sensors if available in cached_data
if cached_data and config_entry and "average" in key:
base_key = key.replace("_average", "")
add_alternate_average_attribute(
attributes,
cached_data,
base_key,
config_entry=config_entry,
)

View file

@ -10,26 +10,24 @@ All calculators inherit from BaseCalculator and have access to coordinator data.
from __future__ import annotations
from .base import TibberPricesBaseCalculator
from .daily_stat import TibberPricesDailyStatCalculator
from .interval import TibberPricesIntervalCalculator
from .lifecycle import TibberPricesLifecycleCalculator
from .metadata import TibberPricesMetadataCalculator
from .rolling_hour import TibberPricesRollingHourCalculator
from .timing import TibberPricesTimingCalculator
from .trend import TibberPricesTrendCalculator
from .volatility import TibberPricesVolatilityCalculator
from .window_24h import TibberPricesWindow24hCalculator
from .base import BaseCalculator
from .daily_stat import DailyStatCalculator
from .interval import IntervalCalculator
from .metadata import MetadataCalculator
from .rolling_hour import RollingHourCalculator
from .timing import TimingCalculator
from .trend import TrendCalculator
from .volatility import VolatilityCalculator
from .window_24h import Window24hCalculator
__all__ = [
"TibberPricesBaseCalculator",
"TibberPricesDailyStatCalculator",
"TibberPricesIntervalCalculator",
"TibberPricesLifecycleCalculator",
"TibberPricesMetadataCalculator",
"TibberPricesRollingHourCalculator",
"TibberPricesTimingCalculator",
"TibberPricesTrendCalculator",
"TibberPricesVolatilityCalculator",
"TibberPricesWindow24hCalculator",
"BaseCalculator",
"DailyStatCalculator",
"IntervalCalculator",
"MetadataCalculator",
"RollingHourCalculator",
"TimingCalculator",
"TrendCalculator",
"VolatilityCalculator",
"Window24hCalculator",
]

View file

@ -4,10 +4,6 @@ from __future__ import annotations
from typing import TYPE_CHECKING, Any
from custom_components.tibber_prices.coordinator.helpers import (
get_intervals_for_day_offsets,
)
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator import (
TibberPricesDataUpdateCoordinator,
@ -16,7 +12,7 @@ if TYPE_CHECKING:
from homeassistant.core import HomeAssistant
class TibberPricesBaseCalculator:
class BaseCalculator:
"""
Base class for all sensor value calculators.
@ -60,9 +56,9 @@ class TibberPricesBaseCalculator:
return self._coordinator.data
@property
def price_info(self) -> list[dict[str, Any]]:
"""Get price info (intervals list) from coordinator data."""
return self.coordinator_data.get("priceInfo", [])
def price_info(self) -> dict[str, Any]:
"""Get price information from coordinator data."""
return self.coordinator_data.get("priceInfo", {})
@property
def user_data(self) -> dict[str, Any]:
@ -71,116 +67,5 @@ class TibberPricesBaseCalculator:
@property
def currency(self) -> str:
"""Get currency code from coordinator data."""
return self.coordinator_data.get("currency", "EUR")
# Smart data access methods with built-in None-safety
def get_intervals(self, day_offset: int) -> list[dict]:
"""
Get price intervals for a specific day with None-safety.
Uses get_intervals_for_day_offsets() to abstract data structure access.
Args:
day_offset: Day offset (-1=yesterday, 0=today, 1=tomorrow).
Returns:
List of interval dictionaries, empty list if unavailable.
"""
if not self.coordinator_data:
return []
return get_intervals_for_day_offsets(self.coordinator_data, [day_offset])
@property
def intervals_today(self) -> list[dict]:
"""Get today's intervals with None-safety."""
return self.get_intervals(0)
@property
def intervals_tomorrow(self) -> list[dict]:
"""Get tomorrow's intervals with None-safety."""
return self.get_intervals(1)
@property
def intervals_yesterday(self) -> list[dict]:
"""Get yesterday's intervals with None-safety."""
return self.get_intervals(-1)
def find_interval_at_offset(self, offset: int) -> dict | None:
"""
Find interval at given offset from current time with bounds checking.
Args:
offset: Offset from current interval (0=current, 1=next, -1=previous).
Returns:
Interval dictionary or None if out of bounds or unavailable.
"""
if not self.coordinator_data:
return None
from custom_components.tibber_prices.utils.price import ( # noqa: PLC0415 - avoid circular import
find_price_data_for_interval,
)
time = self.coordinator.time
target_time = time.get_interval_offset_time(offset)
return find_price_data_for_interval(self.coordinator.data, target_time, time=time)
def safe_get_from_interval(
self,
interval: dict[str, Any],
key: str,
default: Any = None,
) -> Any:
"""
Safely get a value from an interval dictionary.
Args:
interval: Interval dictionary.
key: Key to retrieve.
default: Default value if key not found.
Returns:
Value from interval or default.
"""
return interval.get(key, default) if interval else default
def has_data(self) -> bool:
"""
Check if coordinator has any data available.
Returns:
True if data is available, False otherwise.
"""
return bool(self.coordinator_data)
def has_price_info(self) -> bool:
"""
Check if price info is available in coordinator data.
Returns:
True if price info exists, False otherwise.
"""
return bool(self.price_info)
def get_day_intervals(self, day_offset: int) -> list[dict]:
"""
Get intervals for a specific day from coordinator data.
This is an alias for get_intervals() with consistent naming.
Args:
day_offset: Day offset (-1=yesterday, 0=today, 1=tomorrow).
Returns:
List of interval dictionaries, empty list if unavailable.
"""
return self.get_intervals(day_offset)
"""Get currency code from price info."""
return self.price_info.get("currency", "EUR")

View file

@ -2,6 +2,7 @@
from __future__ import annotations
from datetime import timedelta
from typing import TYPE_CHECKING
from custom_components.tibber_prices.const import (
@ -15,8 +16,9 @@ from custom_components.tibber_prices.sensor.helpers import (
aggregate_level_data,
aggregate_rating_data,
)
from homeassistant.util import dt as dt_util
from .base import TibberPricesBaseCalculator
from .base import BaseCalculator
if TYPE_CHECKING:
from collections.abc import Callable
@ -26,7 +28,7 @@ if TYPE_CHECKING:
)
class TibberPricesDailyStatCalculator(TibberPricesBaseCalculator):
class DailyStatCalculator(BaseCalculator):
"""
Calculator for daily statistics.
@ -49,8 +51,8 @@ class TibberPricesDailyStatCalculator(TibberPricesBaseCalculator):
self,
*,
day: str = "today",
stat_func: Callable[[list[float]], float] | Callable[[list[float]], tuple[float, float | None]],
) -> float | tuple[float, float | None] | None:
stat_func: Callable[[list[float]], float],
) -> float | None:
"""
Unified method for daily statistics (min/max/avg within calendar day).
@ -59,30 +61,39 @@ class TibberPricesDailyStatCalculator(TibberPricesBaseCalculator):
Args:
day: "today" or "tomorrow" - which calendar day to calculate for.
stat_func: Statistical function (min, max, or lambda for avg/median).
stat_func: Statistical function (min, max, or lambda for avg).
Returns:
Price value in subunit currency units (cents/øre), or None if unavailable.
For average functions: tuple of (avg, median) where median may be None.
For min/max functions: single float value.
Price value in minor currency units (cents/øre), or None if unavailable.
"""
if not self.has_data():
if not self.coordinator_data:
return None
# Get local midnight boundaries based on the requested day using TimeService
time = self.coordinator.time
local_midnight, local_midnight_next_day = time.get_day_boundaries(day)
price_info = self.price_info
# Get local midnight boundaries based on the requested day
local_midnight = dt_util.as_local(dt_util.start_of_local_day(dt_util.now()))
if day == "tomorrow":
local_midnight = local_midnight + timedelta(days=1)
local_midnight_next_day = local_midnight + timedelta(days=1)
# Collect all prices and their intervals from both today and tomorrow data
# that fall within the target day's local date boundaries
price_intervals = []
for day_offset in [0, 1]: # today=0, tomorrow=1
for price_data in self.get_intervals(day_offset):
starts_at = price_data.get("startsAt") # Already datetime in local timezone
if not starts_at:
for day_key in ["today", "tomorrow"]:
for price_data in price_info.get(day_key, []):
starts_at_str = price_data.get("startsAt")
if not starts_at_str:
continue
starts_at = dt_util.parse_datetime(starts_at_str)
if starts_at is None:
continue
# Convert to local timezone for comparison
starts_at = dt_util.as_local(starts_at)
# Include price if it starts within the target day's local date boundaries
if local_midnight <= starts_at < local_midnight_next_day:
total_price = price_data.get("total")
@ -99,25 +110,7 @@ class TibberPricesDailyStatCalculator(TibberPricesBaseCalculator):
# Find the extreme value and store its interval for later use in attributes
prices = [pi["price"] for pi in price_intervals]
result = stat_func(prices)
# Check if result is a tuple (avg, median) from average functions
if isinstance(result, tuple):
value, median = result
# Store the interval (for avg, use first interval as reference)
if price_intervals:
self._last_extreme_interval = price_intervals[0]["interval"]
# Convert to display currency units based on config
avg_result = round(get_price_value(value, config_entry=self.coordinator.config_entry), 2)
median_result = (
round(get_price_value(median, config_entry=self.coordinator.config_entry), 2)
if median is not None
else None
)
return avg_result, median_result
# Single value result (min/max functions)
value = result
value = stat_func(prices)
# Store the interval with the extreme price for use in attributes
for pi in price_intervals:
@ -125,8 +118,8 @@ class TibberPricesDailyStatCalculator(TibberPricesBaseCalculator):
self._last_extreme_interval = pi["interval"]
break
# Return in configured display currency units with 2 decimals
result = get_price_value(value, config_entry=self.coordinator.config_entry)
# Always return in minor currency units (cents/øre) with 2 decimals
result = get_price_value(value, in_euro=False)
return round(result, 2)
def get_daily_aggregated_value(
@ -149,22 +142,35 @@ class TibberPricesDailyStatCalculator(TibberPricesBaseCalculator):
Aggregated level/rating value (lowercase), or None if unavailable.
"""
if not self.has_data():
if not self.coordinator_data:
return None
# Get local midnight boundaries based on the requested day using TimeService
time = self.coordinator.time
local_midnight, local_midnight_next_day = time.get_day_boundaries(day)
price_info = self.price_info
# Get local midnight boundaries based on the requested day
local_midnight = dt_util.as_local(dt_util.start_of_local_day(dt_util.now()))
if day == "tomorrow":
local_midnight = local_midnight + timedelta(days=1)
elif day == "yesterday":
local_midnight = local_midnight - timedelta(days=1)
local_midnight_next_day = local_midnight + timedelta(days=1)
# Collect all intervals from both today and tomorrow data
# that fall within the target day's local date boundaries
day_intervals = []
for day_offset in [-1, 0, 1]: # yesterday=-1, today=0, tomorrow=1
for price_data in self.get_intervals(day_offset):
starts_at = price_data.get("startsAt") # Already datetime in local timezone
if not starts_at:
for day_key in ["yesterday", "today", "tomorrow"]:
for price_data in price_info.get(day_key, []):
starts_at_str = price_data.get("startsAt")
if not starts_at_str:
continue
starts_at = dt_util.parse_datetime(starts_at_str)
if starts_at is None:
continue
# Convert to local timezone for comparison
starts_at = dt_util.as_local(starts_at)
# Include interval if it starts within the target day's local date boundaries
if local_midnight <= starts_at < local_midnight_next_day:
day_intervals.append(price_data)

View file

@ -2,11 +2,14 @@
from __future__ import annotations
from datetime import timedelta
from typing import TYPE_CHECKING
from custom_components.tibber_prices.const import get_display_unit_factor
from custom_components.tibber_prices.const import MINUTES_PER_INTERVAL
from custom_components.tibber_prices.utils.price import find_price_data_for_interval
from homeassistant.util import dt as dt_util
from .base import TibberPricesBaseCalculator
from .base import BaseCalculator
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator import (
@ -14,7 +17,7 @@ if TYPE_CHECKING:
)
class TibberPricesIntervalCalculator(TibberPricesBaseCalculator):
class IntervalCalculator(BaseCalculator):
"""
Calculator for interval-based sensors.
@ -36,7 +39,7 @@ class TibberPricesIntervalCalculator(TibberPricesBaseCalculator):
self._last_rating_level: str | None = None
self._last_rating_difference: float | None = None
def get_interval_value( # noqa: PLR0911
def get_interval_value(
self,
*,
interval_offset: int,
@ -57,31 +60,31 @@ class TibberPricesIntervalCalculator(TibberPricesBaseCalculator):
None if data unavailable.
"""
if not self.has_data():
if not self.coordinator_data:
return None
interval_data = self.find_interval_at_offset(interval_offset)
price_info = self.price_info
now = dt_util.now()
target_time = now + timedelta(minutes=MINUTES_PER_INTERVAL * interval_offset)
interval_data = find_price_data_for_interval(price_info, target_time)
if not interval_data:
return None
# Extract value based on type
if value_type == "price":
price = self.safe_get_from_interval(interval_data, "total")
price = interval_data.get("total")
if price is None:
return None
price = float(price)
# Return in base currency if in_euro=True, otherwise in display unit
if in_euro:
return price
factor = get_display_unit_factor(self.config_entry)
return round(price * factor, 2)
return price if in_euro else round(price * 100, 2)
if value_type == "level":
level = self.safe_get_from_interval(interval_data, "level")
level = interval_data.get("level")
return level.lower() if level else None
# For rating: extract rating_level
rating = self.safe_get_from_interval(interval_data, "rating_level")
rating = interval_data.get("rating_level")
return rating.lower() if rating else None
def get_price_level_value(self) -> str | None:
@ -116,16 +119,18 @@ class TibberPricesIntervalCalculator(TibberPricesBaseCalculator):
Rating level (lowercase), or None if unavailable.
"""
if not self.has_data() or rating_type != "current":
if not self.coordinator_data or rating_type != "current":
self._last_rating_difference = None
self._last_rating_level = None
return None
current_interval = self.find_interval_at_offset(0)
now = dt_util.now()
price_info = self.price_info
current_interval = find_price_data_for_interval(price_info, now)
if current_interval:
rating_level = self.safe_get_from_interval(current_interval, "rating_level")
difference = self.safe_get_from_interval(current_interval, "difference")
rating_level = current_interval.get("rating_level")
difference = current_interval.get("difference")
if rating_level is not None:
self._last_rating_difference = float(difference) if difference is not None else None
self._last_rating_level = rating_level

View file

@ -1,184 +0,0 @@
"""Calculator for data lifecycle status tracking."""
from __future__ import annotations
from datetime import datetime, timedelta
from custom_components.tibber_prices.coordinator.constants import UPDATE_INTERVAL
from .base import TibberPricesBaseCalculator
# Constants for lifecycle state determination
FRESH_DATA_THRESHOLD_MINUTES = 5 # Data is "fresh" within 5 minutes of API fetch
TOMORROW_CHECK_HOUR = 13 # After 13:00, we actively check for tomorrow data
TURNOVER_WARNING_SECONDS = 900 # Warn 15 minutes before midnight (last quarter-hour: 23:45-00:00)
class TibberPricesLifecycleCalculator(TibberPricesBaseCalculator):
"""Calculate data lifecycle status and metadata."""
def get_lifecycle_state(self) -> str:
"""
Determine current data lifecycle state.
Returns one of:
- "cached": Using cached data (normal operation)
- "fresh": Just fetched from API (within 5 minutes)
- "refreshing": Currently fetching data from API
- "searching_tomorrow": After 13:00, actively looking for tomorrow data
- "turnover_pending": Last interval of day (23:45-00:00, midnight approaching)
- "error": Last API call failed
Priority order (highest to lowest):
1. refreshing - Active operation has highest priority
2. error - Errors must be immediately visible
3. turnover_pending - Important event at 23:45, should stay visible
4. searching_tomorrow - Stable during search phase (13:00-~15:00)
5. fresh - Informational only, lowest priority among active states
6. cached - Default fallback
"""
coordinator = self.coordinator
current_time = coordinator.time.now()
# Priority 1: Check if actively fetching (highest priority)
if coordinator._is_fetching: # noqa: SLF001 - Internal state access for lifecycle tracking
return "refreshing"
# Priority 2: Check if last update failed
# If coordinator has last_exception set, the last fetch failed
if coordinator.last_exception is not None:
return "error"
# Priority 3: Check if midnight turnover is pending (last quarter of day: 23:45-00:00)
midnight = coordinator.time.as_local(current_time).replace(
hour=0, minute=0, second=0, microsecond=0
) + timedelta(days=1)
time_to_midnight = (midnight - coordinator.time.as_local(current_time)).total_seconds()
if 0 < time_to_midnight <= TURNOVER_WARNING_SECONDS: # Within 15 minutes of midnight (23:45-00:00)
return "turnover_pending"
# Priority 4: Check if we're in tomorrow data search mode (after 13:00 and tomorrow missing)
# This should remain stable during the search phase, not flicker with "fresh" every 15 minutes
now_local = coordinator.time.as_local(current_time)
if now_local.hour >= TOMORROW_CHECK_HOUR and coordinator._needs_tomorrow_data(): # noqa: SLF001 - Internal state access
return "searching_tomorrow"
# Priority 5: Check if data is fresh (within 5 minutes of last API fetch)
# Lower priority than searching_tomorrow to avoid state flickering during search phase
if coordinator._last_price_update: # noqa: SLF001 - Internal state access for lifecycle tracking
age = current_time - coordinator._last_price_update # noqa: SLF001
if age <= timedelta(minutes=FRESH_DATA_THRESHOLD_MINUTES):
return "fresh"
# Priority 6: Default - using cached data
return "cached"
def get_next_api_poll_time(self) -> datetime | None:
"""
Calculate when the next API poll attempt will occur.
Timer #1 runs every 15 minutes FROM INTEGRATION START, not at fixed boundaries.
For example, if integration started at 13:07, timer runs at 13:07, 13:22, 13:37, 13:52.
Returns:
Next poll time when tomorrow data will be fetched (predictive).
Logic:
- If before 13:00 today: Show today 13:00 (when tomorrow-search begins)
- If after 13:00 today AND tomorrow data missing: Show next Timer #1 execution (intensive polling)
- If after 13:00 today AND tomorrow data present: Show tomorrow 13:00 (predictive!)
"""
coordinator = self.coordinator
current_time = coordinator.time.now()
now_local = coordinator.time.as_local(current_time)
# Check if tomorrow data is missing
tomorrow_missing = coordinator._needs_tomorrow_data() # noqa: SLF001
# Get tomorrow date for time calculations
_, tomorrow_midnight = coordinator.time.get_day_boundaries("today")
# Case 1: Before 13:00 today - next poll is today at 13:xx:xx (when tomorrow-search begins)
if now_local.hour < TOMORROW_CHECK_HOUR:
# Calculate exact time based on Timer #1 offset (minute and second precision)
if coordinator._last_coordinator_update is not None: # noqa: SLF001
last_update_local = coordinator.time.as_local(coordinator._last_coordinator_update) # noqa: SLF001
# Timer offset: minutes + seconds past the quarter-hour
minutes_past_quarter = last_update_local.minute % 15
seconds_offset = last_update_local.second
# Calculate first timer execution at or after 13:00 today
# Just apply timer offset to 13:00 (first quarter-hour mark >= 13:00)
# Timer runs at X:04:37 → Next poll at 13:04:37
return now_local.replace(
hour=TOMORROW_CHECK_HOUR,
minute=minutes_past_quarter,
second=seconds_offset,
microsecond=0,
)
# Fallback: No timer history yet
return now_local.replace(hour=TOMORROW_CHECK_HOUR, minute=0, second=0, microsecond=0)
# Case 2: After 13:00 today AND tomorrow data missing - actively polling now
if tomorrow_missing:
# Calculate next Timer #1 execution based on last coordinator update
if coordinator._last_coordinator_update is not None: # noqa: SLF001
next_timer = coordinator._last_coordinator_update + UPDATE_INTERVAL # noqa: SLF001
return coordinator.time.as_local(next_timer)
# Fallback: If we don't know when last update was, estimate from now
# (Should rarely happen - only on first startup before first Timer #1 run)
return now_local + UPDATE_INTERVAL
# Case 3: After 13:00 today AND tomorrow data present - PREDICTIVE: next fetch is tomorrow 13:xx
# After midnight turnover, tomorrow becomes today, and we'll need NEW tomorrow data
# Calculate tomorrow's first Timer #1 execution after 13:00 based on current timer offset
tomorrow_midnight = now_local.replace(hour=0, minute=0, second=0, microsecond=0) + timedelta(days=1)
tomorrow_13 = tomorrow_midnight.replace(hour=TOMORROW_CHECK_HOUR, minute=0, second=0, microsecond=0)
# If we know the last coordinator update, calculate the timer offset
if coordinator._last_coordinator_update is not None: # noqa: SLF001
last_update_local = coordinator.time.as_local(coordinator._last_coordinator_update) # noqa: SLF001
# Calculate offset: minutes + seconds past the quarter-hour boundary
# Example: Timer runs at 13:04:37 → offset is 4 minutes 37 seconds from 13:00:00
minutes_past_quarter = last_update_local.minute % 15
seconds_offset = last_update_local.second
# Find first Timer #1 execution at or after 13:00:00 tomorrow
# Start at 13:00:00 and add offset
candidate_time = tomorrow_13.replace(minute=minutes_past_quarter, second=seconds_offset, microsecond=0)
# If this is before 13:00, add 15 minutes (first timer after 13:00)
# Example: If offset is :59:30, candidate would be 12:59:30, so we add 15min → 13:14:30
if candidate_time < tomorrow_13:
candidate_time += UPDATE_INTERVAL
return candidate_time
# Fallback: If we don't know timer offset yet, assume 13:00:00
return tomorrow_13
def get_api_calls_today(self) -> int:
"""Get the number of API calls made today."""
coordinator = self.coordinator
# Reset counter if day changed
current_date = coordinator.time.now().date()
if coordinator._last_api_call_date != current_date: # noqa: SLF001 - Internal state access
return 0
return coordinator._api_calls_today # noqa: SLF001
def has_tomorrow_data(self) -> bool:
"""
Check if tomorrow's price data is available.
Returns:
True if tomorrow data exists in the pool.
"""
return not self.coordinator._needs_tomorrow_data() # noqa: SLF001

View file

@ -2,10 +2,10 @@
from __future__ import annotations
from .base import TibberPricesBaseCalculator
from .base import BaseCalculator
class TibberPricesMetadataCalculator(TibberPricesBaseCalculator):
class MetadataCalculator(BaseCalculator):
"""
Calculator for home metadata, metering point, and subscription data.

View file

@ -8,18 +8,18 @@ from custom_components.tibber_prices.const import (
DEFAULT_PRICE_RATING_THRESHOLD_HIGH,
DEFAULT_PRICE_RATING_THRESHOLD_LOW,
)
from custom_components.tibber_prices.coordinator.helpers import get_intervals_for_day_offsets
from custom_components.tibber_prices.entity_utils import find_rolling_hour_center_index
from custom_components.tibber_prices.sensor.helpers import (
aggregate_average_data,
aggregate_level_data,
aggregate_price_data,
aggregate_rating_data,
)
from homeassistant.util import dt as dt_util
from .base import TibberPricesBaseCalculator
from .base import BaseCalculator
class TibberPricesRollingHourCalculator(TibberPricesBaseCalculator):
class RollingHourCalculator(BaseCalculator):
"""
Calculator for rolling hour values (5-interval windows).
@ -32,7 +32,7 @@ class TibberPricesRollingHourCalculator(TibberPricesBaseCalculator):
*,
hour_offset: int = 0,
value_type: str = "price",
) -> str | float | tuple[float | None, float | None] | None:
) -> str | float | None:
"""
Unified method to get aggregated values from 5-interval rolling window.
@ -44,24 +44,24 @@ class TibberPricesRollingHourCalculator(TibberPricesBaseCalculator):
Returns:
Aggregated value based on type:
- "price": float or tuple[float, float | None] (avg, median)
- "price": float (average price in minor currency units)
- "level": str (aggregated level: "very_cheap", "cheap", etc.)
- "rating": str (aggregated rating: "low", "normal", "high")
"""
if not self.has_data():
if not self.coordinator_data:
return None
# Get all available price data (yesterday, today, tomorrow)
all_prices = get_intervals_for_day_offsets(self.coordinator_data, [-1, 0, 1])
# Get all available price data
price_info = self.price_info
all_prices = price_info.get("yesterday", []) + price_info.get("today", []) + price_info.get("tomorrow", [])
if not all_prices:
return None
# Find center index for the rolling window
time = self.coordinator.time
now = time.now()
center_idx = find_rolling_hour_center_index(all_prices, now, hour_offset, time=time)
now = dt_util.now()
center_idx = find_rolling_hour_center_index(all_prices, now, hour_offset)
if center_idx is None:
return None
@ -75,13 +75,13 @@ class TibberPricesRollingHourCalculator(TibberPricesBaseCalculator):
if not window_data:
return None
return self.aggregate_window_data(window_data, value_type)
return self._aggregate_window_data(window_data, value_type)
def aggregate_window_data(
def _aggregate_window_data(
self,
window_data: list[dict],
value_type: str,
) -> str | float | tuple[float | None, float | None] | None:
) -> str | float | None:
"""
Aggregate data from multiple intervals based on value type.
@ -90,10 +90,7 @@ class TibberPricesRollingHourCalculator(TibberPricesBaseCalculator):
value_type: "price" | "level" | "rating".
Returns:
Aggregated value based on type:
- "price": tuple[float, float | None] (avg, median)
- "level": str
- "rating": str
Aggregated value based on type.
"""
# Get thresholds from config for rating aggregation
@ -106,12 +103,9 @@ class TibberPricesRollingHourCalculator(TibberPricesBaseCalculator):
DEFAULT_PRICE_RATING_THRESHOLD_HIGH,
)
# Handle price aggregation - return tuple directly
if value_type == "price":
return aggregate_average_data(window_data, self.config_entry)
# Map other value types to aggregation functions
# Map value types to aggregation functions
aggregators = {
"price": lambda data: aggregate_price_data(data),
"level": lambda data: aggregate_level_data(data),
"rating": lambda data: aggregate_rating_data(data, threshold_low, threshold_high),
}

View file

@ -10,18 +10,21 @@ This module handles all timing-related calculations for period-based sensors:
The calculator provides smart defaults:
- Active period show current period timing
- No active show next period timing
- No more periods 0 for numeric values, None for timestamps
- No active show next period timing
- No more periods 0 for numeric values, None for timestamps
"""
from datetime import datetime
from .base import TibberPricesBaseCalculator # Constants
from homeassistant.util import dt as dt_util
from .base import BaseCalculator
# Constants
PROGRESS_GRACE_PERIOD_SECONDS = 60 # Show 100% for 1 minute after period ends
class TibberPricesTimingCalculator(TibberPricesBaseCalculator):
class TimingCalculator(BaseCalculator):
"""
Calculator for period timing sensors.
@ -65,11 +68,11 @@ class TibberPricesTimingCalculator(TibberPricesBaseCalculator):
- None if no relevant period data available
"""
if not self.has_data():
if not self.coordinator.data:
return None
# Get period data from coordinator
periods_data = self.coordinator_data.get("pricePeriods", {})
periods_data = self.coordinator.data.get("periods", {})
period_data = periods_data.get(period_type)
if not period_data or not period_data.get("periods"):
@ -77,13 +80,12 @@ class TibberPricesTimingCalculator(TibberPricesBaseCalculator):
return 0 if value_type in ("remaining_minutes", "progress", "next_in_minutes") else None
period_summaries = period_data["periods"]
time = self.coordinator.time
now = time.now()
now = dt_util.now()
# Find current, previous and next periods
current_period = self._find_active_period(period_summaries)
previous_period = self._find_previous_period(period_summaries)
next_period = self._find_next_period(period_summaries, skip_current=bool(current_period))
current_period = self._find_active_period(period_summaries, now)
previous_period = self._find_previous_period(period_summaries, now)
next_period = self._find_next_period(period_summaries, now, skip_current=bool(current_period))
# Delegate to specific calculators
return self._calculate_timing_value(value_type, current_period, previous_period, next_period, now)
@ -104,46 +106,26 @@ class TibberPricesTimingCalculator(TibberPricesBaseCalculator):
),
"period_duration": lambda: self._calc_period_duration(current_period, next_period),
"next_start_time": lambda: next_period.get("start") if next_period else None,
"remaining_minutes": lambda: (self._calc_remaining_minutes(current_period) if current_period else 0),
"remaining_minutes": lambda: (self._calc_remaining_minutes(current_period, now) if current_period else 0),
"progress": lambda: self._calc_progress_with_grace_period(current_period, previous_period, now),
"next_in_minutes": lambda: (self._calc_next_in_minutes(next_period) if next_period else None),
"next_in_minutes": lambda: (self._calc_next_in_minutes(next_period, now) if next_period else None),
}
calculator = calculators.get(value_type)
return calculator() if calculator else None
def _find_active_period(self, periods: list) -> dict | None:
"""
Find currently active period.
Args:
periods: List of period dictionaries
Returns:
Currently active period or None
"""
time = self.coordinator.time
def _find_active_period(self, periods: list, now: datetime) -> dict | None:
"""Find currently active period."""
for period in periods:
start = period.get("start")
end = period.get("end")
if start and end and time.is_current_interval(start, end):
if start and end and start <= now < end:
return period
return None
def _find_previous_period(self, periods: list) -> dict | None:
"""
Find the most recent period that has already ended.
Args:
periods: List of period dictionaries
Returns:
Most recent past period or None
"""
time = self.coordinator.time
past_periods = [p for p in periods if p.get("end") and time.is_in_past(p["end"])]
def _find_previous_period(self, periods: list, now: datetime) -> dict | None:
"""Find the most recent period that has already ended."""
past_periods = [p for p in periods if p.get("end") and p.get("end") <= now]
if not past_periods:
return None
@ -152,21 +134,20 @@ class TibberPricesTimingCalculator(TibberPricesBaseCalculator):
past_periods.sort(key=lambda p: p["end"], reverse=True)
return past_periods[0]
def _find_next_period(self, periods: list, *, skip_current: bool = False) -> dict | None:
def _find_next_period(self, periods: list, now: datetime, *, skip_current: bool = False) -> dict | None:
"""
Find next future period.
Args:
periods: List of period dictionaries
skip_current: If True, try to skip the first future period (to get next-next)
If only one future period exists, return it anyway (pragmatic fallback)
now: Current time
skip_current: If True, skip the first future period (to get next-next)
Returns:
Next period dict or None if no future periods
"""
time = self.coordinator.time
future_periods = [p for p in periods if p.get("start") and time.is_in_future(p["start"])]
future_periods = [p for p in periods if p.get("start") and p.get("start") > now]
if not future_periods:
return None
@ -174,57 +155,29 @@ class TibberPricesTimingCalculator(TibberPricesBaseCalculator):
# Sort by start time to ensure correct order
future_periods.sort(key=lambda p: p["start"])
# If skip_current requested and we have multiple periods, return second
# If only one period left, return it anyway (pragmatic: better than showing unknown)
# Return second period if skip_current=True (next-next), otherwise first (next)
if skip_current and len(future_periods) > 1:
return future_periods[1]
# Default: return first future period
return future_periods[0] if future_periods else None
if not skip_current and future_periods:
return future_periods[0]
return None
def _calc_remaining_minutes(self, period: dict) -> int:
"""
Calculate ROUNDED minutes until period ends.
Uses standard rounding (0.5 rounds up) to match Home Assistant frontend
relative time display. This ensures sensor values match what users see
in the UI ("in X minutes").
Args:
period: Period dictionary
Returns:
Rounded minutes until period ends (matches HA frontend display)
"""
time = self.coordinator.time
def _calc_remaining_minutes(self, period: dict, now: datetime) -> float:
"""Calculate minutes until period ends."""
end = period.get("end")
if not end:
return 0
return time.minutes_until_rounded(end)
delta = end - now
return max(0, delta.total_seconds() / 60)
def _calc_next_in_minutes(self, period: dict) -> int:
"""
Calculate ROUNDED minutes until next period starts.
Uses standard rounding (0.5 rounds up) to match Home Assistant frontend
relative time display. This ensures sensor values match what users see
in the UI ("in X minutes").
Args:
period: Period dictionary
Returns:
Rounded minutes until period starts (matches HA frontend display)
"""
time = self.coordinator.time
def _calc_next_in_minutes(self, period: dict, now: datetime) -> float:
"""Calculate minutes until period starts."""
start = period.get("start")
if not start:
return 0
return time.minutes_until_rounded(start)
delta = start - now
return max(0, delta.total_seconds() / 60)
def _calc_period_duration(self, current_period: dict | None, next_period: dict | None) -> float | None:
"""

View file

@ -12,18 +12,18 @@ Caching strategy:
- Current trend + next change: Cached centrally for 60s to avoid duplicate calculations
"""
from datetime import datetime
from datetime import datetime, timedelta
from typing import TYPE_CHECKING, Any
from custom_components.tibber_prices.const import get_display_unit_factor
from custom_components.tibber_prices.coordinator.helpers import get_intervals_for_day_offsets
from custom_components.tibber_prices.utils.average import calculate_mean, calculate_next_n_hours_mean
from custom_components.tibber_prices.const import MINUTES_PER_INTERVAL
from custom_components.tibber_prices.utils.average import calculate_next_n_hours_avg
from custom_components.tibber_prices.utils.price import (
calculate_price_trend,
find_price_data_for_interval,
)
from homeassistant.util import dt as dt_util
from .base import TibberPricesBaseCalculator
from .base import BaseCalculator
if TYPE_CHECKING:
from custom_components.tibber_prices.coordinator import (
@ -34,7 +34,7 @@ if TYPE_CHECKING:
MIN_HOURS_FOR_LATER_HALF = 3 # Minimum hours needed to calculate later half average
class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
class TrendCalculator(BaseCalculator):
"""
Calculator for price trend sensors.
@ -80,7 +80,7 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
if self._cached_trend_value is not None and self._trend_attributes:
return self._cached_trend_value
if not self.has_data():
if not self.coordinator.data:
return None
# Get current interval price and timestamp
@ -89,41 +89,38 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
return None
current_interval_price = float(current_interval["total"])
time = self.coordinator.time
current_starts_at = time.get_interval_time(current_interval)
current_starts_at = dt_util.parse_datetime(current_interval["startsAt"])
if current_starts_at is None:
return None
current_starts_at = dt_util.as_local(current_starts_at)
# Get next interval timestamp (basis for calculation)
next_interval_start = time.get_next_interval_start()
next_interval_start = current_starts_at + timedelta(minutes=MINUTES_PER_INTERVAL)
# Get future mean price (ignore median for trend calculation)
future_mean, _ = calculate_next_n_hours_mean(self.coordinator.data, hours, time=self.coordinator.time)
if future_mean is None:
# Get future average price
future_avg = calculate_next_n_hours_avg(self.coordinator.data, hours)
if future_avg is None:
return None
# Get configured thresholds from options
threshold_rising = self.config.get("price_trend_threshold_rising", 5.0)
threshold_falling = self.config.get("price_trend_threshold_falling", -5.0)
threshold_strongly_rising = self.config.get("price_trend_threshold_strongly_rising", 6.0)
threshold_strongly_falling = self.config.get("price_trend_threshold_strongly_falling", -6.0)
volatility_threshold_moderate = self.config.get("volatility_threshold_moderate", 15.0)
volatility_threshold_high = self.config.get("volatility_threshold_high", 30.0)
# Prepare data for volatility-adaptive thresholds
today_prices = self.intervals_today
tomorrow_prices = self.intervals_tomorrow
price_info = self.coordinator.data.get("priceInfo", {})
today_prices = price_info.get("today", [])
tomorrow_prices = price_info.get("tomorrow", [])
all_intervals = today_prices + tomorrow_prices
lookahead_intervals = self.coordinator.time.minutes_to_intervals(hours * 60)
lookahead_intervals = hours * 4 # Convert hours to 15-minute intervals
# Calculate trend with volatility-adaptive thresholds
trend_state, diff_pct, trend_value = calculate_price_trend(
trend_state, diff_pct = calculate_price_trend(
current_interval_price,
future_mean,
future_avg,
threshold_rising=threshold_rising,
threshold_falling=threshold_falling,
threshold_strongly_rising=threshold_strongly_rising,
threshold_strongly_falling=threshold_strongly_falling,
volatility_adjustment=True, # Always enabled
lookahead_intervals=lookahead_intervals,
all_intervals=all_intervals,
@ -131,26 +128,19 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
volatility_threshold_high=volatility_threshold_high,
)
# Determine icon color based on trend state (5-level scale)
# Strongly rising/falling uses more intense colors
# Determine icon color based on trend state
icon_color = {
"strongly_rising": "var(--error-color)", # Red for strongly rising (very expensive)
"rising": "var(--warning-color)", # Orange/Yellow for rising prices
"stable": "var(--state-icon-color)", # Default gray for stable prices
"rising": "var(--error-color)", # Red/Orange for rising prices (expensive)
"falling": "var(--success-color)", # Green for falling prices (cheaper)
"strongly_falling": "var(--success-color)", # Green for strongly falling (great deal)
"stable": "var(--state-icon-color)", # Default gray for stable prices
}.get(trend_state, "var(--state-icon-color)")
# Convert prices to display currency unit based on configuration
factor = get_display_unit_factor(self.config_entry)
# Store attributes in sensor-specific dictionary AND cache the trend value
self._trend_attributes = {
"timestamp": next_interval_start,
"trend_value": trend_value,
"timestamp": next_interval_start.isoformat(),
f"trend_{hours}h_%": round(diff_pct, 1),
f"next_{hours}h_avg": round(future_mean * factor, 2),
"interval_count": lookahead_intervals,
f"next_{hours}h_avg": round(future_avg * 100, 2),
"interval_count": hours * 4,
"threshold_rising": threshold_rising,
"threshold_falling": threshold_falling,
"icon_color": icon_color,
@ -161,13 +151,11 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
# Get second half average for longer periods
later_half_avg = self._calculate_later_half_average(hours, next_interval_start)
if later_half_avg is not None:
self._trend_attributes[f"second_half_{hours}h_avg"] = round(later_half_avg * factor, 2)
self._trend_attributes[f"second_half_{hours}h_avg"] = round(later_half_avg * 100, 2)
# Calculate incremental change: how much does the later half differ from current?
# CRITICAL: Use abs() for negative prices and allow calculation for all non-zero prices
# Example: current=-10, later=-5 → diff=5, pct=5/abs(-10)*100=+50% (correctly shows increase)
if current_interval_price != 0:
later_half_diff = ((later_half_avg - current_interval_price) / abs(current_interval_price)) * 100
if current_interval_price > 0:
later_half_diff = ((later_half_avg - current_interval_price) / current_interval_price) * 100
self._trend_attributes[f"second_half_{hours}h_diff_from_current_%"] = round(later_half_diff, 1)
# Cache the trend value for consistency
@ -259,30 +247,30 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
Average price for the later half intervals, or None if insufficient data
"""
if not self.has_data():
if not self.coordinator.data:
return None
today_prices = self.intervals_today
tomorrow_prices = self.intervals_tomorrow
price_info = self.coordinator.data.get("priceInfo", {})
today_prices = price_info.get("today", [])
tomorrow_prices = price_info.get("tomorrow", [])
all_prices = today_prices + tomorrow_prices
if not all_prices:
return None
# Calculate which intervals belong to the later half
time = self.coordinator.time
total_intervals = time.minutes_to_intervals(hours * 60)
total_intervals = hours * 4
first_half_intervals = total_intervals // 2
interval_duration = time.get_interval_duration()
later_half_start = next_interval_start + (interval_duration * first_half_intervals)
later_half_end = next_interval_start + (interval_duration * total_intervals)
later_half_start = next_interval_start + timedelta(minutes=MINUTES_PER_INTERVAL * first_half_intervals)
later_half_end = next_interval_start + timedelta(minutes=MINUTES_PER_INTERVAL * total_intervals)
# Collect prices in the later half
later_prices = []
for price_data in all_prices:
starts_at = time.get_interval_time(price_data)
starts_at = dt_util.parse_datetime(price_data["startsAt"])
if starts_at is None:
continue
starts_at = dt_util.as_local(starts_at)
if later_half_start <= starts_at < later_half_end:
price = price_data.get("total")
@ -290,7 +278,7 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
later_prices.append(float(price))
if later_prices:
return calculate_mean(later_prices)
return sum(later_prices) / len(later_prices)
return None
@ -308,8 +296,7 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
trend_cache_duration_seconds = 60 # Cache for 1 minute
# Check if we have a valid cache
time = self.coordinator.time
now = time.now()
now = dt_util.now()
if (
self._trend_calculation_cache is not None
and self._trend_calculation_timestamp is not None
@ -318,16 +305,18 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
return self._trend_calculation_cache
# Validate coordinator data
if not self.has_data():
if not self.coordinator.data:
return None
all_intervals = get_intervals_for_day_offsets(self.coordinator_data, [-1, 0, 1])
current_interval = find_price_data_for_interval(self.coordinator.data, now, time=time)
price_info = self.coordinator.data.get("priceInfo", {})
all_intervals = price_info.get("today", []) + price_info.get("tomorrow", [])
current_interval = find_price_data_for_interval(price_info, now)
if not all_intervals or not current_interval:
return None
current_interval_start = time.get_interval_time(current_interval)
current_interval_start = dt_util.parse_datetime(current_interval["startsAt"])
current_interval_start = dt_util.as_local(current_interval_start) if current_interval_start else None
if not current_interval_start:
return None
@ -357,11 +346,11 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
# Combine momentum + future outlook to get ACTUAL current trend
if len(future_intervals) >= min_intervals_for_trend and future_prices:
future_mean = calculate_mean(future_prices)
future_avg = sum(future_prices) / len(future_prices)
current_trend_state = self._combine_momentum_with_future(
current_momentum=current_momentum,
current_price=current_price,
future_mean=future_mean,
future_avg=future_avg,
context={
"all_intervals": all_intervals,
"current_index": current_index,
@ -391,15 +380,14 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
# Calculate duration of current trend
trend_duration_minutes = None
if trend_start_time:
time = self.coordinator.time
# Duration is negative of minutes_until (time in the past)
trend_duration_minutes = -int(time.minutes_until(trend_start_time))
duration = now - trend_start_time
trend_duration_minutes = int(duration.total_seconds() / 60)
# Calculate minutes until change
minutes_until_change = None
if next_change_time:
time = self.coordinator.time
minutes_until_change = int(time.minutes_until(next_change_time))
time_diff = next_change_time - now
minutes_until_change = int(time_diff.total_seconds() / 60)
result = {
"current_trend_state": current_trend_state,
@ -422,8 +410,6 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
return {
"rising": self.config.get("price_trend_threshold_rising", 5.0),
"falling": self.config.get("price_trend_threshold_falling", -5.0),
"strongly_rising": self.config.get("price_trend_threshold_strongly_rising", 6.0),
"strongly_falling": self.config.get("price_trend_threshold_strongly_falling", -6.0),
"moderate": self.config.get("volatility_threshold_moderate", 15.0),
"high": self.config.get("volatility_threshold_high", 30.0),
}
@ -438,7 +424,7 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
current_index: Index of current interval
Returns:
Momentum direction: "strongly_rising", "rising", "stable", "falling", or "strongly_falling"
Momentum direction: "rising", "falling", or "stable"
"""
# Look back 1 hour (4 intervals) for quick reaction
@ -461,91 +447,64 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
weighted_sum = sum(price * weight for price, weight in zip(trailing_prices, weights, strict=True))
weighted_avg = weighted_sum / sum(weights)
# Calculate momentum with thresholds
# Using same logic as 5-level trend: 3% for normal, 6% (2x) for strong
# Calculate momentum with 3% threshold
momentum_threshold = 0.03
strong_momentum_threshold = 0.06
diff = (current_price - weighted_avg) / abs(weighted_avg) if weighted_avg != 0 else 0
diff = (current_price - weighted_avg) / weighted_avg
# Determine momentum level based on thresholds
if diff >= strong_momentum_threshold:
momentum = "strongly_rising"
elif diff > momentum_threshold:
momentum = "rising"
elif diff <= -strong_momentum_threshold:
momentum = "strongly_falling"
elif diff < -momentum_threshold:
momentum = "falling"
else:
momentum = "stable"
return momentum
if diff > momentum_threshold:
return "rising"
if diff < -momentum_threshold:
return "falling"
return "stable"
def _combine_momentum_with_future(
self,
*,
current_momentum: str,
current_price: float,
future_mean: float,
future_avg: float,
context: dict,
) -> str:
"""
Combine momentum analysis with future outlook to determine final trend.
Uses 5-level scale: strongly_rising, rising, stable, falling, strongly_falling.
Momentum intensity is preserved when future confirms the trend direction.
Args:
current_momentum: Current momentum direction (5-level scale)
current_momentum: Current momentum direction (rising/falling/stable)
current_price: Current interval price
future_mean: Average price in future window
future_avg: Average price in future window
context: Dict with all_intervals, current_index, lookahead_intervals, thresholds
Returns:
Final trend direction (5-level scale)
Final trend direction: "rising", "falling", or "stable"
"""
# Use calculate_price_trend for consistency with 5-level logic
if current_momentum == "rising":
# We're in uptrend - does it continue?
return "rising" if future_avg >= current_price * 0.98 else "falling"
if current_momentum == "falling":
# We're in downtrend - does it continue?
return "falling" if future_avg <= current_price * 1.02 else "rising"
# current_momentum == "stable" - what's coming?
all_intervals = context["all_intervals"]
current_index = context["current_index"]
lookahead_intervals = context["lookahead_intervals"]
thresholds = context["thresholds"]
lookahead_for_volatility = all_intervals[current_index : current_index + lookahead_intervals]
future_trend, _, _ = calculate_price_trend(
trend_state, _ = calculate_price_trend(
current_price,
future_mean,
future_avg,
threshold_rising=thresholds["rising"],
threshold_falling=thresholds["falling"],
threshold_strongly_rising=thresholds["strongly_rising"],
threshold_strongly_falling=thresholds["strongly_falling"],
volatility_adjustment=True,
lookahead_intervals=lookahead_intervals,
all_intervals=lookahead_for_volatility,
volatility_threshold_moderate=thresholds["moderate"],
volatility_threshold_high=thresholds["high"],
)
# Check if momentum and future trend are aligned (same direction)
momentum_rising = current_momentum in ("rising", "strongly_rising")
momentum_falling = current_momentum in ("falling", "strongly_falling")
future_rising = future_trend in ("rising", "strongly_rising")
future_falling = future_trend in ("falling", "strongly_falling")
if momentum_rising and future_rising:
# Both indicate rising - use the stronger signal
if current_momentum == "strongly_rising" or future_trend == "strongly_rising":
return "strongly_rising"
return "rising"
if momentum_falling and future_falling:
# Both indicate falling - use the stronger signal
if current_momentum == "strongly_falling" or future_trend == "strongly_falling":
return "strongly_falling"
return "falling"
# Conflicting signals or stable momentum - trust future trend calculation
return future_trend
return trend_state
def _calculate_standard_trend(
self,
@ -567,17 +526,15 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
if not standard_future_prices:
return "stable"
standard_future_mean = calculate_mean(standard_future_prices)
standard_future_avg = sum(standard_future_prices) / len(standard_future_prices)
current_price = float(current_interval["total"])
standard_lookahead_volatility = all_intervals[current_index : current_index + standard_lookahead]
current_trend_3h, _, _ = calculate_price_trend(
current_trend_3h, _ = calculate_price_trend(
current_price,
standard_future_mean,
standard_future_avg,
threshold_rising=thresholds["rising"],
threshold_falling=thresholds["falling"],
threshold_strongly_rising=thresholds["strongly_rising"],
threshold_strongly_falling=thresholds["strongly_falling"],
volatility_adjustment=True,
lookahead_intervals=standard_lookahead,
all_intervals=standard_lookahead_volatility,
@ -589,10 +546,9 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
def _find_current_interval_index(self, all_intervals: list, current_interval_start: datetime) -> int | None:
"""Find the index of current interval in all_intervals list."""
time = self.coordinator.time
for idx, interval in enumerate(all_intervals):
interval_start = time.get_interval_time(interval)
if interval_start and interval_start == current_interval_start:
interval_start = dt_util.parse_datetime(interval["startsAt"])
if interval_start and dt_util.as_local(interval_start) == current_interval_start:
return idx
return None
@ -621,15 +577,15 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
intervals_in_3h = 12 # 3 hours = 12 intervals @ 15min each
# Scan backward to find when trend changed TO current state
time = self.coordinator.time
for i in range(current_index - 1, max(-1, current_index - 97), -1):
if i < 0:
break
interval = all_intervals[i]
interval_start = time.get_interval_time(interval)
interval_start = dt_util.parse_datetime(interval["startsAt"])
if not interval_start:
continue
interval_start = dt_util.as_local(interval_start)
# Calculate trend at this past interval
future_intervals = all_intervals[i + 1 : i + intervals_in_3h + 1]
@ -640,18 +596,16 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
if not future_prices:
continue
future_mean = calculate_mean(future_prices)
future_avg = sum(future_prices) / len(future_prices)
price = float(interval["total"])
# Calculate trend at this past point
lookahead_for_volatility = all_intervals[i : i + intervals_in_3h]
trend_state, _, _ = calculate_price_trend(
trend_state, _ = calculate_price_trend(
price,
future_mean,
future_avg,
threshold_rising=thresholds["rising"],
threshold_falling=thresholds["falling"],
threshold_strongly_rising=thresholds["strongly_rising"],
threshold_strongly_falling=thresholds["strongly_falling"],
volatility_adjustment=True,
lookahead_intervals=intervals_in_3h,
all_intervals=lookahead_for_volatility,
@ -663,9 +617,9 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
if trend_state != current_trend_state:
# Found the change point - the NEXT interval is where current trend started
next_interval = all_intervals[i + 1]
trend_start = time.get_interval_time(next_interval)
trend_start = dt_util.parse_datetime(next_interval["startsAt"])
if trend_start:
return trend_start, trend_state
return dt_util.as_local(trend_start), trend_state
# Reached data boundary - current trend extends beyond available data
return None, None
@ -688,7 +642,6 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
Timestamp of next trend change, or None if no change in next 24h
"""
time = self.coordinator.time
intervals_in_3h = 12 # 3 hours = 12 intervals @ 15min each
current_index = scan_params["current_index"]
current_trend_state = scan_params["current_trend_state"]
@ -697,9 +650,10 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
for i in range(current_index + 1, min(current_index + 97, len(all_intervals))):
interval = all_intervals[i]
interval_start = time.get_interval_time(interval)
interval_start = dt_util.parse_datetime(interval["startsAt"])
if not interval_start:
continue
interval_start = dt_util.as_local(interval_start)
# Skip if this interval is in the past
if interval_start <= now:
@ -714,18 +668,16 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
if not future_prices:
continue
future_mean = calculate_mean(future_prices)
future_avg = sum(future_prices) / len(future_prices)
current_price = float(interval["total"])
# Calculate trend at this future point
lookahead_for_volatility = all_intervals[i : i + intervals_in_3h]
trend_state, _, _ = calculate_price_trend(
trend_state, _ = calculate_price_trend(
current_price,
future_mean,
future_avg,
threshold_rising=thresholds["rising"],
threshold_falling=thresholds["falling"],
threshold_strongly_rising=thresholds["strongly_rising"],
threshold_strongly_falling=thresholds["strongly_falling"],
volatility_adjustment=True,
lookahead_intervals=intervals_in_3h,
all_intervals=lookahead_for_volatility,
@ -737,20 +689,17 @@ class TibberPricesTrendCalculator(TibberPricesBaseCalculator):
# We want to find ANY change from current state, including changes to/from stable
if trend_state != current_trend_state:
# Store details for attributes
time = self.coordinator.time
minutes_until = int(time.minutes_until(interval_start))
# Convert prices to display currency unit
factor = get_display_unit_factor(self.config_entry)
time_diff = interval_start - now
minutes_until = int(time_diff.total_seconds() / 60)
self._trend_change_attributes = {
"direction": trend_state,
"from_direction": current_trend_state,
"minutes_until_change": minutes_until,
"current_price_now": round(float(current_interval["total"]) * factor, 2),
"price_at_change": round(current_price * factor, 2),
"avg_after_change": round(future_mean * factor, 2),
"trend_diff_%": round((future_mean - current_price) / current_price * 100, 1),
"current_price_now": round(float(current_interval["total"]) * 100, 2),
"price_at_change": round(current_price * 100, 2),
"avg_after_change": round(future_avg * 100, 2),
"trend_diff_%": round((future_avg - current_price) / current_price * 100, 1),
}
return interval_start

View file

@ -4,30 +4,20 @@ from __future__ import annotations
from typing import TYPE_CHECKING
from custom_components.tibber_prices.const import (
CONF_VOLATILITY_THRESHOLD_HIGH,
CONF_VOLATILITY_THRESHOLD_MODERATE,
CONF_VOLATILITY_THRESHOLD_VERY_HIGH,
DEFAULT_VOLATILITY_THRESHOLD_HIGH,
DEFAULT_VOLATILITY_THRESHOLD_MODERATE,
DEFAULT_VOLATILITY_THRESHOLD_VERY_HIGH,
get_display_unit_factor,
)
from custom_components.tibber_prices.entity_utils import add_icon_color_attribute
from custom_components.tibber_prices.sensor.attributes import (
add_volatility_type_attributes,
get_prices_for_volatility,
)
from custom_components.tibber_prices.utils.average import calculate_mean
from custom_components.tibber_prices.utils.price import calculate_volatility_with_cv
from custom_components.tibber_prices.utils.price import calculate_volatility_level
from .base import TibberPricesBaseCalculator
from .base import BaseCalculator
if TYPE_CHECKING:
from typing import Any
class TibberPricesVolatilityCalculator(TibberPricesBaseCalculator):
class VolatilityCalculator(BaseCalculator):
"""
Calculator for price volatility analysis.
@ -61,28 +51,20 @@ class TibberPricesVolatilityCalculator(TibberPricesBaseCalculator):
Volatility level: "low", "moderate", "high", "very_high", or None if unavailable.
"""
if not self.has_data():
if not self.coordinator_data:
return None
price_info = self.price_info
# Get volatility thresholds from config
thresholds = {
"threshold_moderate": self.config.get(
CONF_VOLATILITY_THRESHOLD_MODERATE,
DEFAULT_VOLATILITY_THRESHOLD_MODERATE,
),
"threshold_high": self.config.get(CONF_VOLATILITY_THRESHOLD_HIGH, DEFAULT_VOLATILITY_THRESHOLD_HIGH),
"threshold_very_high": self.config.get(
CONF_VOLATILITY_THRESHOLD_VERY_HIGH,
DEFAULT_VOLATILITY_THRESHOLD_VERY_HIGH,
),
"threshold_moderate": self.config.get("volatility_threshold_moderate", 5.0),
"threshold_high": self.config.get("volatility_threshold_high", 15.0),
"threshold_very_high": self.config.get("volatility_threshold_very_high", 30.0),
}
# Get prices based on volatility type
prices_to_analyze = get_prices_for_volatility(
volatility_type,
self.coordinator.data,
time=self.coordinator.time,
)
prices_to_analyze = get_prices_for_volatility(volatility_type, price_info)
if not prices_to_analyze:
return None
@ -91,24 +73,21 @@ class TibberPricesVolatilityCalculator(TibberPricesBaseCalculator):
price_min = min(prices_to_analyze)
price_max = max(prices_to_analyze)
spread = price_max - price_min
# Use arithmetic mean for volatility calculation (required for coefficient of variation)
price_mean = calculate_mean(prices_to_analyze)
price_avg = sum(prices_to_analyze) / len(prices_to_analyze)
# Convert to display currency unit based on configuration
factor = get_display_unit_factor(self.config_entry)
spread_display = spread * factor
# Convert to minor currency units (ct/øre) for display
spread_minor = spread * 100
# Calculate volatility level AND coefficient of variation
volatility, cv = calculate_volatility_with_cv(prices_to_analyze, **thresholds)
# Calculate volatility level with custom thresholds (pass price list, not spread)
volatility = calculate_volatility_level(prices_to_analyze, **thresholds)
# Store attributes for this sensor
self._last_volatility_attributes = {
"price_spread": round(spread_display, 2),
"price_coefficient_variation_%": round(cv, 2) if cv is not None else None,
"price_volatility": volatility.lower(),
"price_min": round(price_min * factor, 2),
"price_max": round(price_max * factor, 2),
"price_mean": round(price_mean * factor, 2),
"price_spread": round(spread_minor, 2),
"price_volatility": volatility,
"price_min": round(price_min * 100, 2),
"price_max": round(price_max * 100, 2),
"price_avg": round(price_avg * 100, 2),
"interval_count": len(prices_to_analyze),
}
@ -116,13 +95,7 @@ class TibberPricesVolatilityCalculator(TibberPricesBaseCalculator):
add_icon_color_attribute(self._last_volatility_attributes, key="volatility", state_value=volatility)
# Add type-specific attributes
add_volatility_type_attributes(
self._last_volatility_attributes,
volatility_type,
self.coordinator.data,
thresholds,
time=self.coordinator.time,
)
add_volatility_type_attributes(self._last_volatility_attributes, volatility_type, price_info, thresholds)
# Return lowercase for ENUM device class
return volatility.lower()

View file

@ -6,13 +6,13 @@ from typing import TYPE_CHECKING
from custom_components.tibber_prices.entity_utils import get_price_value
from .base import TibberPricesBaseCalculator
from .base import BaseCalculator
if TYPE_CHECKING:
from collections.abc import Callable
class TibberPricesWindow24hCalculator(TibberPricesBaseCalculator):
class Window24hCalculator(BaseCalculator):
"""
Calculator for 24-hour sliding window statistics.
@ -24,7 +24,7 @@ class TibberPricesWindow24hCalculator(TibberPricesBaseCalculator):
self,
*,
stat_func: Callable,
) -> float | tuple[float, float | None] | None:
) -> float | None:
"""
Unified method for 24-hour sliding window statistics.
@ -33,38 +33,20 @@ class TibberPricesWindow24hCalculator(TibberPricesBaseCalculator):
- "leading": Next 24 hours (96 intervals after current)
Args:
stat_func: Function from average_utils (e.g., calculate_current_trailing_mean).
stat_func: Function from average_utils (e.g., calculate_current_trailing_avg).
Returns:
Price value in subunit currency units (cents/øre), or None if unavailable.
For mean functions: tuple of (mean, median) where median may be None.
For min/max functions: single float value.
Price value in minor currency units (cents/øre), or None if unavailable.
"""
if not self.has_data():
if not self.coordinator_data:
return None
result = stat_func(self.coordinator_data, time=self.coordinator.time)
value = stat_func(self.coordinator_data)
# Check if result is a tuple (mean, median) from mean functions
if isinstance(result, tuple):
value, median = result
if value is None:
return None
# Convert to display currency units based on config
mean_result = round(get_price_value(value, config_entry=self.coordinator.config_entry), 2)
median_result = (
round(get_price_value(median, config_entry=self.coordinator.config_entry), 2)
if median is not None
else None
)
return mean_result, median_result
# Single value result (min/max functions)
value = result
if value is None:
return None
# Return in configured display currency units with 2 decimals
result = get_price_value(value, config_entry=self.coordinator.config_entry)
# Always return in minor currency units (cents/øre) with 2 decimals
result = get_price_value(value, in_euro=False)
return round(result, 2)

View file

@ -4,7 +4,9 @@ from __future__ import annotations
from typing import TYPE_CHECKING
from custom_components.tibber_prices.const import DATA_CHART_CONFIG, DOMAIN
import yaml
from custom_components.tibber_prices.const import CONF_CHART_DATA_CONFIG, DOMAIN
if TYPE_CHECKING:
from datetime import datetime
@ -20,7 +22,7 @@ async def call_chartdata_service_async(
config_entry: TibberPricesConfigEntry,
) -> tuple[dict | None, str | None]:
"""
Call get_chartdata service with configuration from configuration.yaml (async).
Call get_chartdata service with user-configured YAML (async).
Returns:
Tuple of (response, error_message).
@ -28,19 +30,33 @@ async def call_chartdata_service_async(
If failed: (None, error_string)
"""
# Get configuration from hass.data (loaded from configuration.yaml)
domain_data = hass.data.get(DOMAIN, {})
chart_config = domain_data.get(DATA_CHART_CONFIG, {})
# Get user-configured YAML
yaml_config = config_entry.options.get(CONF_CHART_DATA_CONFIG, "")
# Use chart_config directly (already a dict from async_setup)
service_params = dict(chart_config) if chart_config else {}
# Parse YAML if provided, otherwise use empty dict (service defaults)
service_params = {}
if yaml_config and yaml_config.strip():
try:
parsed = yaml.safe_load(yaml_config)
# Ensure we have a dict (yaml.safe_load can return str, int, etc.)
if isinstance(parsed, dict):
service_params = parsed
else:
coordinator.logger.warning(
"YAML configuration must be a dictionary, got %s. Using service defaults.",
type(parsed).__name__,
)
service_params = {}
except yaml.YAMLError as err:
coordinator.logger.warning(
"Invalid chart data YAML configuration: %s. Using service defaults.",
err,
)
service_params = {} # Fall back to service defaults
# Add required entry_id parameter
service_params["entry_id"] = config_entry.entry_id
# Make sure metadata is never requested for this sensor
service_params["metadata"] = "none"
# Call get_chartdata service using official HA service system
try:
response = await hass.services.async_call(
@ -102,7 +118,7 @@ def build_chart_data_attributes(
"""
# Build base attributes with metadata FIRST
attributes: dict[str, object] = {
"timestamp": chart_data_last_update,
"timestamp": chart_data_last_update.isoformat() if chart_data_last_update else None,
}
# Add error message if service call failed

Some files were not shown because too many files have changed in this diff Show more