Skip to content

🌼 Pollen Levels v3.0.0b5 — per-location setup resilience and diagnostics hardening

Pre-release
Pre-release

Choose a tag to compare

View all tags
@eXPerience83 eXPerience83 released this 15 Jun 12:52
v3.0.0.b5
f770205
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

This is the fifth beta for the upcoming Pollen Levels v3 release.

It is a pre-release validation build for the new Home Assistant config subentries architecture, where one parent config entry stores the Google Pollen API key and each configured location is stored as a location subentry.

Beta 5 focuses on making multi-location setups more resilient:

  • One failing location should no longer block healthy locations under the same parent API key.
  • Failed, loaded, and stale locations are now reported separately in diagnostics.
  • Home Assistant Repairs now provide clearer guidance for repeated isolated location setup failures.
  • Runtime language-code handling has been hardened so invalid stored values are ignored instead of being sent to Google.
  • Home Assistant harness coverage has been expanded across setup, migration, flows, services, diagnostics, platforms, and the fixed 5-day request path.

⚠️ This is still a beta pre-release.
Please create a full Home Assistant backup before upgrading.

🚨 Important upgrade notice

Supported upgrade path for this beta

This beta is primarily intended for users upgrading from the latest stable v2 release:

2.3.0 → 3.0.0b5

It can also be used by existing v3 beta testers upgrading from an earlier v3 alpha or beta build.

The v3 migration changes how Pollen Levels stores configuration internally.

Before v3, each location was a separate config entry with its own stored API key.

Starting with v3:

Parent config entry
└── Google Pollen API key
    ├── Location subentry: Home
    ├── Location subentry: Work
    └── Location subentry: Other location

Legacy entries sharing the same Google API key are consolidated under one parent entry. Each previous location becomes one location subentry.

⛔ Downgrade warning

After upgrading to Pollen Levels v3, downgrading back to Pollen Levels 2.x is not supported without restoring a Home Assistant backup.

If you need to go back to 2.x, restore the backup created before installing this beta.

Do not downgrade directly from v3 to v2.x expecting the old config entries to work as before.

⚠️ Breaking changes carried by v3

Beta 5 does not introduce an additional breaking change beyond the v3 beta line, but it still includes the v3 breaking changes already introduced in earlier builds.

v3 config subentries migration

Pollen Levels v3 migrates configuration storage to Home Assistant config subentries.

After upgrading to v3, downgrading to Pollen Levels 2.x is not supported without restoring a backup.

Removed optional _d1 and _d2 pollen type forecast sensors

Starting with beta 4, the optional extra per-day pollen type forecast sensors ending in:

_d1
_d2

are no longer created.

These were the extra forecast entities created for D+1 and D+2 pollen type forecasts.

Forecast data is still available through attributes on the base pollen type, plant, and summary sensors, including:

forecast
tomorrow_value
tomorrow_category
d2_value
d2_category
trend
expected_peak

For the fixed 5-day forecast model, the forecast attribute can expose future offsets:

offset 1 → tomorrow
offset 2 → D+2
offset 3 → D+3
offset 4 → D+4

Existing dashboards, automations, templates, and custom cards that still reference sensor.*_d1 or sensor.*_d2 must be updated.

Migration example

Before:

{{ states("sensor.example_grass_d1") }}
{{ states("sensor.example_grass_d2") }}

After:

{{ state_attr("sensor.example_grass", "tomorrow_value") }}
{{ state_attr("sensor.example_grass", "d2_value") }}

Or using the forecast list directly:

{% set forecast = state_attr("sensor.example_grass", "forecast") or [] %}
{% set tomorrow = forecast | selectattr("offset", "eq", 1) | first %}
{{ tomorrow.value if tomorrow else none }}

✨ What changed since v2.3.0

🧩 New v3 config subentries architecture

Pollen Levels now uses Home Assistant config subentries:

  • One parent config entry per Google Pollen API key.

  • One location subentry per configured location.

  • Multiple locations can share the same API key.

  • Global options live on the parent entry:

    • update interval
    • API response language

  • Location data lives on each subentry:

    • name
    • latitude
    • longitude

Forecast days are no longer configurable. Pollen Levels now always requests the maximum 5-day forecast horizon supported by the Google Maps Pollen API.

This makes the integration cleaner, easier to manage, and better aligned with Home Assistant’s multi-location configuration model.

🏠 Multi-location migration

When upgrading from v2.3.0, existing locations are migrated automatically.

Expected behavior:

  • Existing locations are converted into location subentries.
  • Entries using the same API key are grouped under one parent entry.
  • Entries using different API keys remain under separate parent entries.
  • Existing entity IDs should be preserved.
  • Existing unique IDs should be preserved.
  • Existing devices, dashboards, automations, and history should continue to match after migration.

Please verify your entities after upgrading, especially if you had multiple locations configured before.

🛡 Per-location setup resilience

Beta 5 adds conservative partial setup for v3 location subentries.

If one location has a local, non-auth setup failure, healthy locations under the same parent API key can continue loading.

This is especially useful for multi-location setups where one stored location is temporarily unavailable, invalid, or unable to return usable initial data.

Failed locations do not create placeholder sensors or update buttons.

After fixing the affected location, reload the parent Pollen Levels entry from Home Assistant so the failed location can be retried.

🧰 Home Assistant Repairs for isolated setup failures

Beta 5 adds a Home Assistant Repair warning for repeated isolated location setup failures.

The Repair warning provides privacy-safe details and guidance without exposing API keys, full request URLs, or precise coordinates.

Repair warnings are cleaned up automatically when:

  • the affected location loads successfully after reload
  • the affected location subentry has been removed

🩺 Improved diagnostics

Diagnostics now distinguish between:

  • loaded locations
  • failed locations
  • stale runtime locations

Failed setup metadata is exposed through diagnostics under:

failed_locations

The existing v3 summaries remain available:

registry_summary
runtime_summary

Expected healthy values after reload:

registry_summary.entities.without_subentry = 0
registry_summary.devices.without_subentry = 0
registry_summary.devices.with_legacy_none_association = 0
runtime_summary.stale_location_count = 0
runtime_summary.failed_location_count = 0

API keys are redacted, and coordinates are only included approximately for support purposes.

Beta 5 also removes legacy single-location duplicate diagnostic fields copied from the first location. In v3, per-location diagnostics are now exposed under locations, avoiding misleading top-level data in multi-location setups.

🔘 Per-location “Update now” button

Each location has its own Update now button.

This allows refreshing one loaded location without forcing every configured location to update.

In beta 5, sensors, Update now buttons, and the global Home Assistant action/service only operate on successfully loaded runtime locations.

The global Home Assistant action/service still exists:

pollenlevels.force_update

It continues to refresh all active loaded locations.

Failed or stale runtime locations are skipped.

🧹 Safer stale runtime handling

v3 improves behavior when a location subentry is removed.

The integration avoids refreshing stale runtime locations that may remain temporarily in memory before the parent entry is reloaded.

This affects:

  • sensor setup
  • button setup
  • diagnostics
  • pollenlevels.force_update

If diagnostics report stale runtime data immediately after deleting a location, reload the Pollen Levels parent entry from Home Assistant.

📅 Fixed 5-day forecast model

Forecast days are fixed at 5 for all entries and locations.

The setup and options flows no longer expose configuration options for:

  • forecast days
  • separate per-day pollen type forecast sensors

Existing entries with stored forecast_days or create_forecast_sensors options are upgraded automatically.

🧹 Legacy forecast entity cleanup

Legacy _d1 and _d2 entity registry entries owned by Pollen Levels are removed during setup or reload.

Forecast data remains available through attributes on the base pollen type, plant, and summary sensors.

📈 Forecast attributes for overall pollen risk

The overall_pollen_risk_today summary sensor exposes forecast-style attributes, so compatible Lovelace cards and dashboards can render upcoming-day general pollen risk more easily.

This brings the summary sensor closer to the forecast model used by pollen type and plant sensors.

🌱 Better handling of partial Google Pollen payloads

Sensor setup accepts valid current-day plant_ pollen payload keys.

This avoids treating plant-only valid data as missing pollen data.

Beta 5 also adds coverage for sanitized real 5-day Google Pollen fixtures with partial plant/type entries, helping validate the fixed 5-day forecast path against realistic API responses.

🌐 Hardened language-code handling

Invalid stored API language codes are now ignored instead of being sent to Google as malformed languageCode values.

Language-code validation is centralized so setup, options flow, diagnostics, and runtime handling use consistent rules.

Diagnostics request examples now reflect the normalized language value, or omit it when the stored value is invalid.

🔒 Improved cancellation handling

The global pollenlevels.force_update action correctly propagates asyncio.CancelledError.

This helps Home Assistant shutdown, reload, and task cancellation behave correctly.

🧪 Expanded Home Assistant harness coverage

Beta 5 significantly expands Home Assistant harness coverage.

Coverage now includes:

  • setup
  • unload
  • reload
  • config flow
  • options flow
  • subentry flows
  • parent API-key reauth/reconfigure flows
  • platform entity registration
  • button press behavior
  • services
  • diagnostics
  • fixed days=5 API request behavior
  • migration scenarios
  • parent entries without location subentries
  • isolated partial setup failures
  • Repair warning creation and cleanup

Some duplicated lightweight stub tests were removed where the real Home Assistant harness now provides equivalent coverage.

✅ Recommended validation after upgrading

After installing 3.0.0b5, please check:

  • Pollen Levels loads successfully.
  • Existing entities keep their entity IDs.
  • Existing dashboards and automations still work, except references to removed _d1 / _d2 forecast sensors.
  • Existing history is preserved.
  • Each location appears as a location subentry.
  • Each loaded location has its own Update now button.
  • pollenlevels.force_update still works.
  • Failed or stale locations are not refreshed by pollenlevels.force_update.
  • Forecast attributes are available on base pollen type, plant, and summary sensors.
  • The forecast attribute exposes the expected upcoming-day offsets.
  • Legacy sensor.*_d1 and sensor.*_d2 entities owned by Pollen Levels are removed.
  • Adding a new location works.
  • Reconfiguring a location works.
  • Removing a location works.
  • Reloading the parent entry clears any temporary stale runtime data.
  • A single invalid or temporarily unavailable location does not block healthy sibling locations.
  • Failed location diagnostics appear under failed_locations.
  • Failed, loaded, and stale locations are reported separately in diagnostics.
  • Repair warnings appear for repeated isolated setup failures.
  • Repair warnings clear automatically after the affected location loads successfully or is removed.
  • Invalid stored language values are ignored instead of being sent to Google.

🧪 Beta feedback wanted

Please report issues if you notice:

  • entities renamed unexpectedly
  • duplicated entities
  • missing devices
  • lost history
  • failed migration
  • stale locations still being refreshed
  • failed locations being refreshed by force_update
  • one failed location blocking healthy locations under the same parent entry
  • diagnostics exposing sensitive information
  • diagnostics mixing loaded, failed, and stale locations incorrectly
  • failed-location diagnostics missing or marked incorrectly
  • Repair warnings not appearing for repeated isolated setup failures
  • Repair warnings not clearing after the issue is fixed
  • dashboards/cards not reading forecast attributes correctly
  • legacy _d1 or _d2 entities not being removed
  • invalid stored language values being sent to Google

When opening an issue, please avoid sharing API keys, full request URLs, or precise coordinates.

📌 Summary

Pollen Levels v3.0.0b5 is focused on validating the v3 migration with stronger multi-location resilience before the RC phase.

Main highlights:

  • New Home Assistant config subentries architecture.
  • One parent entry per API key.
  • One location subentry per location.
  • Migration from v2.3.0 with entity/history preservation.
  • Forecast days fixed at 5.
  • Removed optional _d1 / _d2 pollen type forecast sensors.
  • Automatic cleanup of legacy _d1 / _d2 entity registry entries owned by Pollen Levels.
  • Per-location setup failures no longer block healthy sibling locations.
  • Failed setup metadata exposed through diagnostics under failed_locations.
  • Home Assistant Repair warning for repeated isolated location setup failures.
  • Automatic cleanup of stale/fixed setup failure Repair warnings.
  • Diagnostics now separate loaded, failed, and stale locations.
  • Removed legacy top-level duplicate diagnostics copied from the first location.
  • Invalid stored API language codes are ignored instead of being sent to Google.
  • Per-location update buttons.
  • Safer stale runtime handling.
  • Forecast attributes on overall_pollen_risk_today.
  • Expanded Home Assistant harness coverage across the real runtime paths.

Please backup before upgrading, test carefully, and report any migration, diagnostics, Repair, or multi-location setup issue before the RC phase.

What's Changed

Added

  • Added conservative partial setup for v3 location subentries. When one location has a local non-auth setup failure, healthy locations under the same parent API key can continue loading.
  • Added per-location setup failure runtime metadata exposed through diagnostics under failed_locations.
  • Added a Home Assistant Repair warning for repeated isolated location setup failures, with privacy-safe details and guidance to reload the parent entry after fixing the affected location.
  • Added Home Assistant harness coverage for setup, subentry flows, services, diagnostics, platform entity registration, and the fixed 5-day API request.

Changed

  • Sensors, Update now buttons, and the global pollenlevels.force_update action now operate only on successfully loaded runtime locations.
  • Runtime diagnostics now distinguish loaded, failed, and stale locations through separate summary fields.
  • Retryable partial setup failures now schedule a conservative automatic parent reload before surfacing the per-location Repair warning.
  • Replaced duplicated lightweight stub tests with Home Assistant harness tests where the real runtime path now provides equivalent coverage.

Fixed

  • Prevented one invalid or temporarily unavailable location subentry from blocking other healthy locations under the same parent entry.
  • Cleared location setup failure Repair warnings automatically when the affected location loads successfully after a reload.
  • Cleared stale per-location Repair warnings automatically when the affected location subentry has been removed.
  • Avoided relying on Home Assistant issue registry internals when cleaning stale per-location Repair warnings.
  • Corrected failed-location diagnostics so invalid stored locations are not marked as reload-retryable.
  • Kept failed-location registry entries untouched so existing entities and recorder history are not removed because of a local setup failure.
  • Localized the new setup failure Repair warning across all supported locales.
  • Removed legacy single-location duplicate fields from diagnostics. In v3, per-location diagnostics are now exposed only under locations, avoiding misleading top-level data copied from the first location.
  • Passed the config entry into the data update coordinator when supported by Home Assistant, preserving compatibility with newer coordinator contracts.
  • Ignored invalid stored API language codes instead of sending malformed languageCode values to Google.

Changes since beta 4: v3.0.0b4...v3.0.0b5

Full Changelog: v2.3.0...v3.0.0b5

What's Changed

Full Changelog: v2.3.0...v3.0.0.b5

Contributors

eXPerience83
Assets 3
Loading