Resolve a currency symbol to a code wherever it arrives

AlphaESS has started answering moneyType with the symbol rather than an ISO
code - "€" where it used to send "EUR". Home Assistant's monetary device class
only accepts a code, so the symbol had to be resolved before it reached a unit.

The mapping already existed in the sensor platform, so the monetary units were
never wrong, but two things around it were. The Currency Code sensor reports
whatever the API sent, so it now reads "€" - a symbol, from a sensor named for
a code, and the same value goes into the diagnostics download. The parser now
resolves it once, so both report a code.

The other is a symbol that names more than one currency. "$" resolved to USD
whatever the owner's currency, which is wrong for every AUD, NZD and CAD system
- a good share of them - and "¥" resolved to JPY for a Chinese one. An
ambiguous symbol now resolves to the currency Home Assistant is configured for
when that is one of the candidates, and to the most common otherwise. An
unrecognised value still falls back rather than being guessed at.

The mapping moves to its own module so the parser and the sensor platform share
one answer, and it gains 元 and Kč on the way through.

Author: Poshy163

README.md

@@ -440,7 +440,14 @@ discarding the list shape.
 
 ### Currency and daily history sensors
 
-- Monetary sensors now use ISO 4217 currency codes when provided by the API, and fall back to Home Assistant's configured currency when not available.
+- Monetary sensors report an ISO 4217 currency code, which is what Home
+  Assistant's monetary device class accepts. AlphaESS answers `moneyType` with
+  either a code or the symbol and has changed which, so a symbol is resolved to
+  a code. Where a symbol names more than one currency (`$`, `¥`, `kr`) the
+  currency Home Assistant is configured for wins if it is one of them,
+  otherwise the most common is used. An unrecognised value falls back to the
+  configured currency rather than being guessed at. The `Currency Code`
+  diagnostic sensor reports the resolved code, not the raw value.
 - Diagnostic currency sensors are available for troubleshooting:
   - `Currency Code`
 - Daily history energy breakdown sensors are exposed:

custom_components/alphaess/coordinator.py

@@ -31,6 +31,7 @@
     SUBENTRY_TYPE_EV_CHARGER,
     SUBENTRY_TYPE_INVERTER,
 )
+from .currency import normalize_currency_unit
 from .enums import AlphaESSNames
 
 _LOGGER = logging.getLogger(__name__)
@@ -277,7 +278,10 @@ def parse_summary_data(self, sum_data: dict, fallback_currency: str | None = Non
             AlphaESSNames.TodayIncome: self.dp.safe_get(sum_data, "todayIncome"),
         }
 
-        resolved = currency or fallback_currency or "Unknown"
+        # moneyType is sometimes an ISO code and sometimes the symbol; the
+        # sensor named "Currency Code" should report a code either way, and so
+        # should the diagnostics download.
+        resolved = normalize_currency_unit(currency, fallback_currency) or "Unknown"
         data[AlphaESSNames.CurrencyCode] = resolved
         data["Currency"] = resolved
 

custom_components/alphaess/currency.py

@@ -0,0 +1,71 @@
+"""Currency handling for the monetary sensors.
+
+AlphaESS answers `moneyType` with either an ISO 4217 code or the currency
+symbol, and has changed which one it sends. Home Assistant's monetary device
+class only accepts a code, so a symbol has to be resolved to one.
+
+Some symbols name more than one currency, and there the only honest tiebreak
+available is the currency Home Assistant is already configured for: a "$" from
+an inverter belonging to someone running AUD is far more likely to be AUD than
+USD.
+"""
+from __future__ import annotations
+
+# Symbol -> the ISO codes that share it, most common first. A single-entry list
+# is unambiguous and is used whatever Home Assistant is configured for.
+SYMBOL_TO_ISO: dict[str, list[str]] = {
+    "$": ["USD", "AUD", "CAD", "NZD", "SGD", "HKD", "MXN"],
+    "€": ["EUR"],
+    "£": ["GBP"],
+    "¥": ["JPY", "CNY"],
+    "元": ["CNY"],
+    "₩": ["KRW"],
+    "₹": ["INR"],
+    "₽": ["RUB"],
+    "₺": ["TRY"],
+    "R$": ["BRL"],
+    "₫": ["VND"],
+    "₴": ["UAH"],
+    "₱": ["PHP"],
+    "₦": ["NGN"],
+    "Fr": ["CHF"],
+    "kr": ["SEK", "NOK", "DKK", "ISK"],
+    "zł": ["PLN"],
+    "Kč": ["CZK"],
+    "A$": ["AUD"],
+    "C$": ["CAD"],
+    "NZ$": ["NZD"],
+    "R": ["ZAR"],
+}
+
+
+def normalize_currency_unit(value: str | None, fallback: str | None) -> str | None:
+    """Return an ISO 4217 code for a `moneyType`, or the fallback.
+
+    A three-letter code is taken as-is. A symbol naming one currency resolves to
+    it. A symbol naming several resolves to the configured currency when that is
+    one of them, and otherwise to the most common. Anything unrecognised falls
+    back rather than guessing.
+    """
+    if value is None:
+        return fallback
+
+    normalized = value.strip()
+    if not normalized:
+        return fallback
+
+    # Already a 3-letter ISO code
+    if len(normalized) == 3 and normalized.isalpha():
+        return normalized.upper()
+
+    candidates = SYMBOL_TO_ISO.get(normalized)
+    if not candidates:
+        # Unknown symbol - the configured currency is a better answer than a guess.
+        return fallback
+
+    if len(candidates) > 1 and fallback:
+        configured = fallback.strip().upper()
+        if configured in candidates:
+            return configured
+
+    return candidates[0]

custom_components/alphaess/sensor.py

@@ -19,6 +19,7 @@
     WIFI_STATUS_KEYS,
 )
 from .coordinator import AlphaESSDataUpdateCoordinator
+from .currency import normalize_currency_unit
 from .device import build_ev_charger_device_info, build_inverter_device_info
 from .enums import AlphaESSNames
 from .sensorlist import (
@@ -37,58 +38,6 @@
 # Map common currency symbols to ISO 4217 codes.
 # SensorDeviceClass.MONETARY expects an ISO 4217 currency code; raw symbols
 # (e.g. '€') would produce invalid-unit warnings and broken statistics.
-_SYMBOL_TO_ISO: dict[str, str] = {
-    "$": "USD",
-    "€": "EUR",
-    "£": "GBP",
-    "¥": "JPY",
-    "₩": "KRW",
-    "₹": "INR",
-    "₽": "RUB",
-    "₺": "TRY",
-    "R$": "BRL",
-    "₫": "VND",
-    "₴": "UAH",
-    "₱": "PHP",
-    "₦": "NGN",
-    "Fr": "CHF",
-    "kr": "SEK",
-    "zł": "PLN",
-    "A$": "AUD",
-    "C$": "CAD",
-    "NZ$": "NZD",
-    "R": "ZAR",
-}
-
-
-def _normalize_currency_unit(value: str | None, fallback: str | None) -> str | None:
-    """
-    Normalize currency for monetary units to an ISO 4217 code.
-
-    SensorDeviceClass.MONETARY expects an ISO 4217 currency code.
-    If the API returns a known symbol we map it; otherwise we fall back
-    to the HA-configured currency.
-    """
-    if value is None:
-        return fallback
-
-    normalized = value.strip()
-    if not normalized:
-        return fallback
-
-    # Already a 3-letter ISO code
-    if len(normalized) == 3 and normalized.isalpha():
-        return normalized.upper()
-
-    # Try to map a symbol to its ISO code
-    iso = _SYMBOL_TO_ISO.get(normalized)
-    if iso:
-        return iso
-
-    # Unknown symbol — fall back to HA's configured currency
-    return fallback
-
-
 EV_RELATED_KEYS = {
     AlphaESSNames.evchargersn,
     AlphaESSNames.evchargermodel,
@@ -192,7 +141,7 @@ async def async_setup_entry(hass, entry, async_add_entities) -> None:
 
             data = coordinator.data[serial]
             model = data.get("Model")
-            currency = _normalize_currency_unit(
+            currency = normalize_currency_unit(
                 data.get(AlphaESSNames.CurrencyCode) or data.get("Currency"),
                 hass.config.currency,
             )
@@ -273,7 +222,7 @@ async def async_setup_entry(hass, entry, async_add_entities) -> None:
             if not ev_charger:
                 continue
 
-            currency = _normalize_currency_unit(
+            currency = normalize_currency_unit(
                 data.get(AlphaESSNames.CurrencyCode) or data.get("Currency"),
                 hass.config.currency,
             )
@@ -306,7 +255,7 @@ async def async_setup_entry(hass, entry, async_add_entities) -> None:
         if not ev_charger or ev_charger in ev_subentry_serials:
             continue
 
-        currency = _normalize_currency_unit(
+        currency = normalize_currency_unit(
             data.get(AlphaESSNames.CurrencyCode) or data.get("Currency"),
             hass.config.currency,
         )

tests/test_coordinator_parsers.py

@@ -110,6 +110,19 @@ def test_currency_unknown(self, parser):
         data = parser.parse_summary_data({})
         assert data[AlphaESSNames.CurrencyCode] == "Unknown"
 
+    def test_a_symbol_is_reported_as_a_code(self, parser):
+        """AlphaESS switched moneyType from "EUR" to "€"; the sensor is named
+        Currency Code and Home Assistant's monetary class needs one."""
+        data = parser.parse_summary_data({"moneyType": "€", "eload": 5})
+        assert data[AlphaESSNames.CurrencyCode] == "EUR"
+        assert data["Currency"] == "EUR"
+
+    def test_an_ambiguous_symbol_uses_the_configured_currency(self, parser):
+        data = parser.parse_summary_data(
+            {"moneyType": "$"}, fallback_currency="AUD",
+        )
+        assert data[AlphaESSNames.CurrencyCode] == "AUD"
+
     def test_self_consumption_scaling(self, parser):
         data = parser.parse_summary_data(
             {"eselfConsumption": 0.5, "eselfSufficiency": 0.25}

tests/test_helpers.py

@@ -9,7 +9,7 @@
     SUBENTRY_TYPE_EV_CHARGER,
     SUBENTRY_TYPE_INVERTER,
 )
-from custom_components.alphaess.sensor import _normalize_currency_unit
+from custom_components.alphaess.currency import normalize_currency_unit
 
 
 def _entry_with_subentries(subentries):
@@ -29,21 +29,38 @@ def _inverter_subentry(serial, ip="", model=""):
 
 class TestNormalizeCurrencyUnit:
     def test_none_falls_back(self):
-        assert _normalize_currency_unit(None, "EUR") == "EUR"
-        assert _normalize_currency_unit("", "EUR") == "EUR"
-        assert _normalize_currency_unit("  ", "EUR") == "EUR"
+        assert normalize_currency_unit(None, "EUR") == "EUR"
+        assert normalize_currency_unit("", "EUR") == "EUR"
+        assert normalize_currency_unit("  ", "EUR") == "EUR"
 
     def test_iso_code_passthrough(self):
-        assert _normalize_currency_unit("gbp", "EUR") == "GBP"
-        assert _normalize_currency_unit("USD", "EUR") == "USD"
+        assert normalize_currency_unit("gbp", "EUR") == "GBP"
+        assert normalize_currency_unit("USD", "EUR") == "USD"
 
     def test_symbol_mapping(self):
-        assert _normalize_currency_unit("€", "USD") == "EUR"
-        assert _normalize_currency_unit("£", "USD") == "GBP"
-        assert _normalize_currency_unit("$", "EUR") == "USD"
+        assert normalize_currency_unit("€", "USD") == "EUR"
+        assert normalize_currency_unit("£", "USD") == "GBP"
+        assert normalize_currency_unit("$", "EUR") == "USD"
 
     def test_unknown_symbol_falls_back(self):
-        assert _normalize_currency_unit("☃", "AUD") == "AUD"
+        assert normalize_currency_unit("☃", "AUD") == "AUD"
+
+    def test_an_ambiguous_symbol_prefers_the_configured_currency(self):
+        """AlphaESS sells into plenty of dollar and yen markets, and the symbol
+        alone cannot tell them apart. What Home Assistant is set to can."""
+        assert normalize_currency_unit("$", "AUD") == "AUD"
+        assert normalize_currency_unit("$", "nzd") == "NZD"
+        assert normalize_currency_unit("¥", "CNY") == "CNY"
+        assert normalize_currency_unit("kr", "NOK") == "NOK"
+
+    def test_an_ambiguous_symbol_falls_to_the_common_one(self):
+        assert normalize_currency_unit("$", "GBP") == "USD"
+        assert normalize_currency_unit("$", None) == "USD"
+        assert normalize_currency_unit("¥", "GBP") == "JPY"
+
+    def test_an_unambiguous_symbol_ignores_the_configured_currency(self):
+        assert normalize_currency_unit("€", "AUD") == "EUR"
+        assert normalize_currency_unit("A$", "USD") == "AUD"
 
 
 class TestBuildIpAddressMap: