Skip to content

🌼 Pollen Levels v3.0.0rc1

Pre-release
Pre-release

Choose a tag to compare

View all tags
@eXPerience83 eXPerience83 released this 20 Jun 21:56
v3.0.0rc1
4caa72d
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

🌼 Pollen Levels v3.0.0rc1 — v3 release candidate with diagnostics and identity cleanup

This is the first release candidate for the upcoming Pollen Levels v3 release.

It validates 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.

RC1 focuses on final documentation and diagnostics cleanup before the stable v3 release:

  • Clarifies plant sensor identity behavior across API languages.
  • Removes an unused per-location authentication diagnostic flag.
  • Clarifies partial location setup behavior during startup.
  • Documents that diagnostics may include Home Assistant internal entry_id and subentry_id values.

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

🚨 Important upgrade notice

Supported upgrade path for this release candidate

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

2.3.0 → 3.0.0rc1

It can also be used by existing v3 alpha or beta testers upgrading from an earlier v3 pre-release 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 release candidate.

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

⚠️ Breaking changes carried by v3

RC1 does not introduce an additional breaking change beyond the v3 pre-release 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.

🌱 Stable plant sensor identity across API languages

Pollen Levels uses Google plantInfo.code values for plant sensor identity.

These codes have been tested across supported API languages and are treated as stable identifiers for plant sensors.

Localized Google displayName values only affect visible names and attributes.

This means changing the configured API response language may change localized display names, but should not change the underlying plant sensor identity.

🛡 Per-location setup resilience

v3 includes conservative partial setup for 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

v3 adds Home Assistant Repairs for important configuration and migration cases:

  • Invalid stored Pollen Levels location data.
  • Legacy per-day forecast sensors or legacy forecast options.
  • Repeated isolated location setup failures.

If stored location data is invalid, Home Assistant will show guidance to delete and recreate the affected location or restore a backup.

If legacy _d1 / _d2 forecast sensors or options are detected, Home Assistant will warn that dashboards, automations, templates, and custom cards may need to be updated.

If a location repeatedly fails setup while healthy sibling locations can still load, Home Assistant will show a Repair warning with privacy-safe guidance.

Repair warnings are cleaned up automatically when:

  • the affected location loads successfully after reload
  • the affected location subentry has been removed
  • the legacy forecast issue has been resolved

🩺 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.

Diagnostics may include Home Assistant internal entry_id and subentry_id values. These are Home Assistant internal identifiers used to understand which parent entry or location subentry a diagnostic item belongs to.

RC1 removes the unused is_auth_error field from failed location diagnostics.

Authentication failures are handled at the parent/API-key level, so failed location diagnostics no longer expose a per-location authentication flag.

v3 also removes legacy single-location duplicate diagnostic fields copied from the first location. In v3, per-location diagnostics are 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.

Sensors, Update now buttons, and the global Home Assistant action/service operate only 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.

v3 also includes 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 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 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

The v3 pre-release cycle significantly expanded Home Assistant harness coverage.

Coverage 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.0rc1, 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.
  • Reauthenticating the API key works at parent entry level.
  • 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.
  • Failed location diagnostics no longer expose is_auth_error.
  • Diagnostics may include Home Assistant internal entry_id and subentry_id values.
  • 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.
  • Changing API response language does not change plant sensor identity.

🧪 Release candidate 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 API keys, full request URLs, or precise coordinates
  • diagnostics mixing loaded, failed, and stale locations incorrectly
  • failed-location diagnostics missing or marked incorrectly
  • failed-location diagnostics still exposing is_auth_error
  • 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
  • plant sensor identity changing after changing API response language

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

📌 Summary

Pollen Levels v3.0.0rc1 is the first release candidate for the v3 migration.

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.
  • Removed unused is_auth_error from failed location diagnostics.
  • Documented Home Assistant internal entry_id and subentry_id values in diagnostics.
  • Clarified stable plant sensor identity based on Google plantInfo.code.
  • 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, forecast, or multi-location setup issue before the stable v3 release.

What's Changed

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

Contributors

renovate and eXPerience83
Assets 3
Loading