v2.4.9.3

v2.4.9.3

---

New features

• Dynamic entity discovery — Rules, devices, alarms, flows, and target lists added to your Firewalla after the integration loads now appear in Home Assistant automatically at the next poll, without requiring an integration reload or restart.

• Enable Debug Logging toggle — Added to integration options (Settings → Devices & Services → Firewalla → Configure). Enables verbose debug output to the HA log immediately without requiring changes to configuration.yaml or a restart. Reverts to warning-level logging when disabled.

---

Improvements

• Firewall rule display names — Rules now show a human-readable composite label built from action, target, and scope rather than raw UUIDs or internal identifiers. Device-scoped rules resolve the MAC address against the coordinator device list to show the device name. Examples:

  • Block: Test User (notes field set)
  • Allow: deb.debian.org on pi4nut (device scope, MAC resolved)
  • Block: Internet on group 13 (group scope)
  • Block: Intranet on network (network scope)
  • Block: 71.6.167.142 (no scope)
  • Rules with a Notes field set in the Firewalla portal always use that as the primary label. Tip: fill in the Notes field on your rules for the clearest names in HA.

• Rule API pagination — get_rules() now follows next_cursor to retrieve all pages of rules. Previously only the first page was fetched, causing newly-created rules to be silently omitted if the account had enough rules to span multiple pages.

• Rule payload debug logging — Full rule payloads are logged at debug level on each poll when debug logging is enabled, aiding troubleshooting of rule naming and discovery issues.

---

Bug fixes

• Fixed bandwidth sensors (Total Download, Total Upload) causing repeated recorder warnings — changed state class from TOTAL_INCREASING to TOTAL, which correctly models Firewalla's rolling accumulated counters that can decrease when a window expires.

• Fixed a race condition causing a non existing via_device warning in HA logs — box devices are now pre-registered in the HA device registry during async_setup_entry, before any platform sets up entities. This was set to become a hard failure in HA 2025.12.

• Fixed LF/CRLF line ending inconsistency in source files — .gitattributes now enforces LF repo-wide.

---

Upgrade notes

• Full HA restart required after updating.
• No breaking changes. All existing entity unique IDs are unchanged.
• Existing rule entities will be renamed on first reload as display names are now dynamically generated from rule content. Entity unique IDs are unchanged so no automations are broken.
• HA will clear long-term statistics for bandwidth sensors on first restart due to the state class change from TOTAL_INCREASING to TOTAL. Historical data is retained but the statistics reset point will shift — this is expected and correct behaviour.
• Network UUID scopes (on network) and group numeric ID scopes (on group 13) cannot be resolved to display names without additional API endpoints not currently available in the Firewalla MSP API. Use the Notes field in the Firewalla portal to set a friendly name for these rules.

v2.4.9.3-rc.6

Readying for v2.4.9.3 release.

Fixed em dash in switch.py
Updated README.md to reflect changes and update to debug info

v2.4.9.3-rc.5

v2.4.9.3-rc.5

Improvements

• Improved firewall rule display names. Rules now show a composite label built from action, target, and scope rather than raw UUIDs or internal identifiers. Device-scoped rules resolve the MAC address against the coordinator device list to show the device name. Examples:

  • Allow: deb.debian.org on pi4nut (device scope, MAC resolved)
  • Block: Internet on group 13 (group scope)
  • Block: Intranet on network (network scope)
  • Block: 71.6.167.142 (no scope)
  • Rules with notes still use the notes field as the primary label — Block: Test User

• Rule payload debug logging is now retained as a permanent diagnostic aid, visible when Enable Debug Logging is on in integration options.

Known limitations

• Network UUID scopes (e.g. on network) and group numeric ID scopes (e.g. on group 13) cannot be resolved to display names without additional API endpoints not currently available in the Firewalla MSP API. Use the Notes field in the Firewalla portal to set a friendly name for these rules.

Upgrade notes

• Existing rule entities will be renamed on the next integration reload as _attr_name is now dynamically generated. unique_id values are unchanged so no entities are orphaned.

v2.4.9.3-rc.4

Append Rule notes field as name of rule in HA rather than rule UUID.

Added debug temporarily to API response on rules.

v2.4.9.3-rc.3

Bug fixes

• Fixed bandwidth sensors (Total Download, Total Upload) incorrectly using TOTAL_INCREASING state class, causing repeated recorder warnings when Firewalla's rolling counters decreased. Changed to TOTAL, which correctly models an accumulated value that can fluctuate without triggering HA validation.
• Fixed new firewall rules not appearing in Home Assistant — get_rules() previously fetched only the first page of results. Now paginates via next_cursor to retrieve all rules, matching the existing behaviour of get_alarms().
• Fixed via_device warning for box devices — box devices are now pre-registered in the HA device registry during async_setup_entry, before any platform sets up entities. Eliminates the race condition between platform load order and device registry population that was set to become a hard failure in HA 2025.12.

New features

• Added Enable Debug Logging toggle to integration options (Settings → Devices & Services → Firewalla → Configure). Enables verbose debug output to the HA log immediately without requiring changes to configuration.yaml or a restart. Reverts to warning-level logging when disabled.

Upgrade notes

• Full HA restart required after updating.
• No breaking changes. All existing entity unique IDs are unchanged.
• HA will clear long-term statistics for bandwidth sensors on first restart due to the state class change from TOTAL_INCREASING to TOTAL. Historical data is retained but the statistics reset point will shift — this is expected and correct behaviour.

v2.4.9.3-rc.2

v2.4.9.3-rc.2

What's new

• Dynamic entity discovery — Rules, devices, alarms, flows, and target lists added to your Firewalla after the integration loads now appear in Home Assistant automatically at the next poll, without requiring an integration reload or restart.

Bug fixes

• Fixed a race condition causing a non existing via_device warning in HA logs when device entities were created before their parent box device had been registered. This warning was set to become a hard failure in HA 2025.12 — it is now resolved.
• Fixed LF/CRLF line ending inconsistency in source files.

Upgrade notes

• Full HA restart required after updating.
• No breaking changes. All existing entity unique IDs are unchanged.

v2.4.9.3-rc.1

v2.4.9.3-rc.1: Dynamic entity discovery via coordinator listener pattern
Fix new rules, devices, alarms, flows, and target lists not appearing in Home Assistant without an integration reload.
All four platforms previously called async_add_entities exactly once during async_setup_entry. Items added after initial load were correctly fetched by the coordinator but never resulted in new entity instances being created.
Changes:

switch.py — Firewall rules now auto-register on each coordinator poll via async_add_listener
binary_sensor.py — Boxes, devices, rules, and alarms now auto-register on each coordinator poll
device_tracker.py — New network devices now auto-register on each coordinator poll
sensor.py — Per-device sensors, flow sensors, and target list sensors now auto-register on each coordinator poll; MSP aggregate sensors remain static singletons (no change required)
.gitattributes — Enforce LF line endings repo-wide for consistent cross-platform behaviour

Upgrade notes:
Full HA restart required after deploying. No breaking changes to existing entity unique IDs.

v2.4.9.2

v2.4.9.2

Fixes a regression introduced in v2.4.9.1 where the integration could not be added via the UI. The config flow failed with HTTP 500 before the setup form rendered.

Root cause: The subdomain validator (_validate_subdomain) was embedded directly in the voluptuous schema. Home Assistant's voluptuous_serialize library cannot serialise bare Python callables and raises ValueError when attempting to render the form.

Fix: Removed the validator from the schema definition. It is now called explicitly in the form handler before any API call is made, with a proper field-level error displayed if the subdomain is invalid.

v2.4.9.1

v2.4.9.1

Audit Fixes & Hardening

Code review (by Gemini & Claude) completed against the full v2.4.9.1 codebase. Multiple rounds of audit identified and resolved two functional bugs, removed dead code, and hardened two defensive paths.

Fixed

• sensor.py — Added missing coordinator.data None guards to _get_device(), FirewallaFlowSensor.native_value, and FirewallaTargetListSensor._get_tl(). These three methods accessed coordinator.data.get(...) without a None check, which could raise AttributeError during edge-case restarts or transient coordinator failures. All other platform files (binary_sensor.py, switch.py, device_tracker.py) already had this guard — this aligns sensor.py with the rest of the codebase.
• __init__.py — async_remove_config_entry_device now blocks deletion of the MSP service device (msp_global_* identifiers) in addition to box devices. Previously, clicking Delete on the "Firewalla MSP" device card would remove it from the registry, orphaning all MSP-level entities (stats sensors, alarm count, target list sensors) until the next integration reload. Same fix applied to _handle_rename_device to prevent confusing error logs when targeting non-device identifiers.

Changed

• sensor.py — Flow-to-device matching in async_setup_entry now uses a pre-built lookup dict (device_by_id) keyed by uppercased device ID instead of a nested next() scan per flow. Reduces setup complexity from O(N×M) to O(N+M) for users with many devices and flows. Matching behaviour, case normalisation, and None fallback are unchanged.
• const.py — Removed 13 unused constants: BRAND, CONF_SCAN_INTERVAL (shadowed by homeassistant.const), and 11 ATTR_* constants (ATTR_DEVICE_ID, ATTR_DEVICE_NAME, ATTR_NETWORK_ID, ATTR_LAST_SEEN, ATTR_IP_ADDRESS, ATTR_MAC_ADDRESS, ATTR_ONLINE, ATTR_BLOCKED, ATTR_UPLOAD, ATTR_DOWNLOAD, ATTR_BLOCKED_COUNT) that were defined but never imported. ATTR_ALARM_ID and ATTR_RULE_ID remain (actively used by binary_sensor.py and __init__.py).
• binary_sensor.py — _safe_configuration_url now wraps IPv6 addresses in brackets per RFC 2732 (https://[::1] instead of https://::1). IPv4 behaviour unchanged. Near-zero real-world risk (Firewalla boxes use IPv4 public IPs), but the validation path accepted IPv6 input so the URL construction needed to be correct.
• api.py — HTML response detection in _api_request is now case-insensitive (body.lower() before checking for <html). Catches WAF/proxy error pages using <HTML>, <Html>, or other casing variants.

Audit Findings (no action required)

• Security: _safe_configuration_url IP validation, strict subdomain regex, SHA-256 hashed credential storage, and 429-aware backoff all confirmed sound.
• Functionality: Auth error propagation (FirewallaAuthError → ConfigEntryAuthFailed), 204 No Content handling on action endpoints, pagination safety caps, stale device persistence via Store, service cleanup on last entry unload, and entity identity scoping all confirmed correct.

Notes

• All 18 source files pass ast.parse syntax validation.
• Cross-module import verification confirms no broken references from const.py cleanup.
• Files unchanged: coordinator.py, config_flow.py, device_tracker.py, switch.py, helpers.py, manifest.json, hacs.json, services.yaml, strings.json, README.md, all 10 translation files.

v2.4.9

v2.4.9

Fixed

• Auth errors from optional API endpoints now trigger re-auth — Previously, a revoked or expired token was silently ignored when returned by rules, alarms, flows, target lists, or stats endpoints. The broad except Exception handler swallowed FirewallaAuthError, so HA never surfaced a re-auth notification until the next core data fetch. All optional and stats fetches now correctly propagate auth failures as ConfigEntryAuthFailed.

• Config flow no longer misreports server errors as auth failures — A temporary API outage during initial setup previously showed "check your subdomain and API token" instead of "unable to reach the Firewalla API". get_boxes() and get_devices() now return None on API failure (distinct from [] for a genuine empty account), allowing the config flow to display the correct error message.

• Subdomain input is now validated — The config flow now enforces RFC-952/1123 hostname rules on the subdomain field, preventing control characters, spaces, and URL-significant characters from reaching the URL constructor. Input is also normalised to lowercase.

• {"data": null} API responses no longer misinterpreted — The JSON envelope unwrapper now uses a positive type check (list/dict) instead of a negative exclusion list, preventing null payloads from being treated as failed requests.

Improved

• icons.json is now the single source of truth for all entity icons — Removed redundant _attr_icon class attributes and the icon property override from FirewallaRuleSwitch. HA resolves icons from icons.json when translation_key is set, so the Python-side declarations were unnecessary duplicates.

• Removed redundant code across all entity platforms — Cleaned up entity_registry_enabled_default overrides that returned True (already HA's default) and duplicate _attr_translation_key class attributes on sensor subclasses where the parent __init__ already sets the value.

Files Changed

File	Change
coordinator.py	Auth propagation in optional fetches and stats; None coercion from updated api.py
api.py	get_boxes()/get_devices() return None on failure; positive-type envelope unwrap
config_flow.py	Subdomain validation; None vs [] error mapping
sensor.py	Removed redundant icons, translation keys, and enabled defaults
binary_sensor.py	Removed redundant enabled defaults
switch.py	Removed redundant icon property and enabled default
device_tracker.py	Removed redundant enabled default
manifest.json	Version bump to 2.4.9