plugin_solax_ev_charger.py

import logging
from dataclasses import dataclass
from datetime import UTC, datetime, timedelta, timezone
from typing import Any

from homeassistant.components.number import NumberDeviceClass
from homeassistant.components.sensor import SensorDeviceClass, SensorStateClass
from homeassistant.const import (
    PERCENTAGE,
    UnitOfElectricCurrent,
    UnitOfElectricPotential,
    UnitOfEnergy,
    UnitOfFrequency,
    UnitOfPower,
    UnitOfTemperature,
    UnitOfTime,
)
from homeassistant.helpers.entity import (  # type: ignore[attr-defined]
    EntityCategory,
)

from custom_components.solax_modbus.const import (
    REG_HOLDING,
    REG_INPUT,
    REGISTER_S16,
    REGISTER_U16,
    REGISTER_U32,
    REGISTER_WORDS,
    TIME_OPTIONS_SEPARATE_REGISTERS,
    WRITE_MULTI_MODBUS,
    BaseModbusButtonEntityDescription,
    BaseModbusNumberEntityDescription,
    BaseModbusSelectEntityDescription,
    BaseModbusSensorEntityDescription,
    BaseModbusSwitchEntityDescription,
    BaseModbusTimeEntityDescription,
    plugin_base,
    value_function_enable_disable,
    value_function_firmware_decimal_hundredths,
    value_function_separate_registers_time,
)

from .pymodbus_compat import DataType, convert_from_registers

_LOGGER = logging.getLogger(__name__)


# Debug helper for EV charger operations
def _debug_charger_setting(hub_name: str, setting_name: str, value: Any, register: int | None = None, mode: str | None = None) -> None:
    """Log debug information about charger setting changes"""
    mode_info = f" (current mode: {mode})" if mode else ""
    reg_info = f" at register 0x{register:x}" if register else ""
    _LOGGER.debug(f"{hub_name}: EV Charger {setting_name} set to {value}{reg_info}{mode_info}")


""" ============================================================================================
bitmasks  definitions to characterize inverters, ogranized by group
these bitmasks are used in entitydeclarations to determine to which inverters the entity applies
within a group, the bits in an entitydeclaration will be interpreted as OR
between groups, an AND condition is applied, so all gruoups must match.
An empty group (group without active flags) evaluates to True.
example: GEN3 | GEN4 | X1 | X3 | EPS
means:  any inverter of type (GEN3 or GEN4) and (X1 or X3) and (EPS)
An entity can be declared multiple times (with different bitmasks) if the parameters are different for each inverter type
"""

GEN = 0x0001  # base generation for MIC, PV, AC
GEN1 = 0x0001
GEN2 = 0x0002
GEN3 = 0x0004
GEN4 = 0x0008
ALL_GEN_GROUP = GEN1 | GEN2 | GEN3 | GEN4 | GEN

X1 = 0x0100
X3 = 0x0200
ALL_X_GROUP = X1 | X3

POW4 = 0x0080
POW7 = 0x0010
POW11 = 0x0020
POW22 = 0x0040
ALL_POW_GROUP = POW4 | POW7 | POW11 | POW22

# Feature flags — set dynamically in async_determineInverterType based on device registers
OCPP_TYPE = 0x0800  # device reports TypeCharger (0x0023) == 1 (OCPP variant)
ALL_FEATURE_GROUP = OCPP_TYPE

ALLDEFAULT = 0  # should be equivalent to HYBRID | AC | GEN2 | GEN3 | GEN4 | X1 | X3

# ======================= end of bitmask handling code =============================================

SENSOR_TYPES: list[Any] = []

# ====================== find inverter type and details ===========================================


async def async_read_serialnr(hub: Any, address: int) -> str | None:
    _LOGGER.debug(f"{hub.name}: Reading serial number from address 0x{address:x}")
    res = None
    try:
        _LOGGER.debug(f"{hub.name}: Attempting to read holding registers at 0x{address:x}, count=7, unit={hub._modbus_addr}")
        inverter_data = await hub.async_read_holding_registers(unit=hub._modbus_addr, address=address, count=7)
        if not inverter_data.isError():
            _LOGGER.debug(f"{hub.name}: Successfully read registers: {inverter_data.registers[0:7]}")
            raw = convert_from_registers(inverter_data.registers[0:7], DataType.STRING, "big")  # type: ignore[attr-defined]  # Dynamic enum aliasing
            _LOGGER.debug(f"{hub.name}: Converted raw data: {raw} (type: {type(raw)})")
            res = raw.decode("ascii", errors="ignore") if isinstance(raw, (bytes, bytearray)) else str(raw)
            hub.seriesnumber = res
            _LOGGER.debug(f"{hub.name}: Decoded serial number: {res}")
        else:
            _LOGGER.debug(f"{hub.name}: Register read returned error: {inverter_data}")
    except Exception as ex:
        _LOGGER.warning(f"{hub.name}: attempt to read serialnumber failed at 0x{address:x}", exc_info=True)
        _LOGGER.debug(f"{hub.name}: Exception type: {type(ex).__name__}, message: {ex}")
    if not res:
        _LOGGER.warning(f"{hub.name}: reading serial number from address 0x{address:x} failed; other address may succeed")
    _LOGGER.info(f"Read {hub.name} 0x{address:x} serial number before potential swap: {res}")
    return res


async def async_read_firmware(hub: Any, address: int = 0x25) -> float | None:
    """Read firmware version from input register.

    Args:
        hub: The modbus hub instance
        address: Register address (default 0x25)

    Returns:
        float: Firmware version (e.g., 7.07) or None on failure
    """
    _LOGGER.debug(f"{hub.name}: Reading firmware version from address 0x{address:x}")
    res = None
    try:
        _LOGGER.debug(f"{hub.name}: Attempting to read input registers at 0x{address:x}, count=1, unit={hub._modbus_addr}")
        fw_data = await hub.async_read_input_registers(unit=hub._modbus_addr, address=address, count=1)
        if not fw_data.isError():
            fw_raw = fw_data.registers[0]
            res = fw_raw / 100.0  # Decimal hundredths (e.g., 707 → 7.07)
            _LOGGER.debug(f"{hub.name}: Successfully read firmware: raw={fw_raw}, version={res:.2f}")
        else:
            _LOGGER.debug(f"{hub.name}: Register read returned error: {fw_data}")
    except Exception as ex:
        _LOGGER.warning(f"{hub.name}: attempt to read firmware failed at 0x{address:x}", exc_info=True)
        _LOGGER.debug(f"{hub.name}: Exception type: {type(ex).__name__}, message: {ex}")
    if not res:
        _LOGGER.debug(f"{hub.name}: reading firmware from address 0x{address:x} failed")
    return res


# =================================================================================================


@dataclass(kw_only=True, frozen=True)
class SolaXEVChargerModbusButtonEntityDescription(BaseModbusButtonEntityDescription):
    allowedtypes: int = ALLDEFAULT  # maybe 0x0000 (nothing) is a better default choice


@dataclass(kw_only=True, frozen=True)
class SolaXEVChargerModbusNumberEntityDescription(BaseModbusNumberEntityDescription):
    allowedtypes: int = ALLDEFAULT  # maybe 0x0000 (nothing) is a better default choice


@dataclass(kw_only=True, frozen=True)
class SolaXEVChargerModbusSelectEntityDescription(BaseModbusSelectEntityDescription):
    allowedtypes: int = ALLDEFAULT  # maybe 0x0000 (nothing) is a better default choice


@dataclass(kw_only=True, frozen=True)
class SolaXEVChargerModbusSensorEntityDescription(BaseModbusSensorEntityDescription):
    allowedtypes: int = ALLDEFAULT  # maybe 0x0000 (nothing) is a better default choice
    # order16: int = Endian.BIG
    order32: str | None = None  # optional per-sensor 32-bit word order override
    register_data_type: str = REGISTER_U16
    register_type: int = REG_HOLDING


@dataclass(kw_only=True, frozen=True)
class SolaXEVChargerModbusTimeEntityDescription(BaseModbusTimeEntityDescription):
    allowedtypes: int = ALLDEFAULT


# ====================================== Computed value functions  =================================================


def value_function_rtc_evc(initval: Any, descr: Any, datadict: dict[str, Any]) -> datetime | None:
    """Parse EVC RTC block (7 words from 0x61D).

    word[0] = timezone offset in MINUTES (device uses minutes; e.g. UTC+3 → 180,
              negatives as uint16 two's-complement).
    words[1-6] = seconds, minutes, hours, day, month, year (2-digit).

    Attaches the stored timezone directly to the stored time — no UTC assumption,
    no conversion.  Whatever time the device holds is shown as-is with its offset.
    e.g. stored: tz=180, time=11:18  ->  returns 2026-05-01 11:18:00+03:00
    """

    try:
        tz_raw, sec, minute, hour, day, month, year = initval
        tz_minutes = tz_raw if tz_raw <= 32767 else tz_raw - 65536
        tz = timezone(timedelta(minutes=tz_minutes))
        return datetime(2000 + year % 100, month, day, hour, minute, sec, tzinfo=tz)
    except Exception:
        return None


def value_function_sync_rtc_evc(initval: Any, descr: Any, datadict: dict[str, Any]) -> list[tuple[str, int]]:
    """Write timezone (0x61D) then RTC time (0x61E–0x623) in one multi-register write.

    The device displays stored_UTC_time + tz_offset as local time, so we write:
      - 0x61D: the real UTC offset in minutes (e.g. 180 for UTC+3) so the device
               can show correct local time on its own display / app.
      - 0x61E–0x623: current UTC time so the stored instant is always correct.
    """

    utc_now = datetime.now(UTC)
    local_offset = datetime.now().astimezone().utcoffset()
    tz_minutes = int(local_offset.total_seconds() / 60) if local_offset is not None else 0
    tz_u16 = tz_minutes & 0xFFFF  # e.g. UTC+3 → 180; UTC-5 → 65531
    return [
        (REGISTER_U16, tz_u16),  # 0x61D: timezone offset in minutes
        (REGISTER_U16, utc_now.second),  # 0x61E: seconds  (UTC)
        (REGISTER_U16, utc_now.minute),  # 0x61F: minutes  (UTC)
        (REGISTER_U16, utc_now.hour),  # 0x620: hours    (UTC)
        (REGISTER_U16, utc_now.day),  # 0x621: day      (UTC)
        (REGISTER_U16, utc_now.month),  # 0x622: month    (UTC)
        (REGISTER_U16, utc_now.year % 100),  # 0x623: year     (UTC)
    ]


# ================================= Button Declarations ============================================================

BUTTON_TYPES = [
    SolaXEVChargerModbusButtonEntityDescription(
        name="Sync RTC",
        key="sync_rtc",
        register=0x61D,
        write_method=WRITE_MULTI_MODBUS,
        icon="mdi:home-clock",
        value_function=value_function_sync_rtc_evc,
        entity_category=EntityCategory.CONFIG,
    ),
]

# ================================= Number Declarations ============================================================

NUMBER_TYPES = [
    ###
    #
    # Data only number types
    #
    ###
    ###
    #
    #  Normal number types
    #
    ###
    SolaXEVChargerModbusNumberEntityDescription(
        name="Overload Limit",
        key="overload_limit",
        register=0x611,
        fmt="i",
        native_min_value=260,
        native_max_value=300,
        native_step=1,
        native_unit_of_measurement=UnitOfElectricPotential.VOLT,
        device_class=NumberDeviceClass.VOLTAGE,
        entity_category=EntityCategory.CONFIG,
    ),
    SolaXEVChargerModbusNumberEntityDescription(
        name="Undervoltage Limit",
        key="undervoltage_limit",
        register=0x612,
        fmt="i",
        native_min_value=80,
        native_max_value=160,
        native_step=1,
        native_unit_of_measurement=UnitOfElectricPotential.VOLT,
        device_class=NumberDeviceClass.VOLTAGE,
        entity_category=EntityCategory.CONFIG,
    ),
    SolaXEVChargerModbusNumberEntityDescription(
        name="Main Breaker Limit",
        key="main_breaker_limit",
        register=0x614,
        fmt="i",
        native_min_value=11,
        native_max_value=300,
        native_step=1,
        native_unit_of_measurement=UnitOfElectricCurrent.AMPERE,
        device_class=NumberDeviceClass.CURRENT,
        entity_category=EntityCategory.CONFIG,
    ),
    SolaXEVChargerModbusNumberEntityDescription(
        name="Datahub Charge Current",
        key="datahub_charge_current",
        register=0x624,
        allowedtypes=GEN1,  # GEN1 only - not available on GEN2
        fmt="f",
        native_min_value=6,
        native_max_value=32,
        native_step=0.1,
        scale=0.01,
        native_unit_of_measurement=UnitOfElectricCurrent.AMPERE,
        device_class=NumberDeviceClass.CURRENT,
    ),
    SolaXEVChargerModbusNumberEntityDescription(
        name="Charge Current",
        key="charge_current",
        register=0x628,
        fmt="f",
        native_min_value=6,
        native_max_value=32,
        native_step=0.1,
        scale=0.01,
        native_unit_of_measurement=UnitOfElectricCurrent.AMPERE,
        device_class=NumberDeviceClass.CURRENT,
    ),
    SolaXEVChargerModbusNumberEntityDescription(
        name="Max Charge Current",
        key="max_charge_current",
        register=0x668,
        fmt="f",
        native_min_value=6,
        native_max_value=32,
        native_step=0.1,
        scale=0.01,
        native_unit_of_measurement=UnitOfElectricCurrent.AMPERE,
        device_class=NumberDeviceClass.CURRENT,
    ),
    SolaXEVChargerModbusNumberEntityDescription(
        name="Modbus Address",
        key="modbus_address",
        register=0x640,
        fmt="i",
        native_min_value=1,
        native_max_value=247,
        native_step=1,
        icon="mdi:identifier",
        entity_category=EntityCategory.CONFIG,
    ),
    SolaXEVChargerModbusNumberEntityDescription(
        name="Smart Boost Energy",
        key="smart_boost_energy",
        register=0x63A,
        fmt="i",
        native_min_value=0,
        native_max_value=200,
        native_step=1,
        native_unit_of_measurement=UnitOfEnergy.KILO_WATT_HOUR,
        device_class=NumberDeviceClass.ENERGY,
        entity_category=EntityCategory.CONFIG,
    ),
    SolaXEVChargerModbusNumberEntityDescription(
        name="OCPP Charge Current",
        key="ocpp_charge_current",
        register=0x61B,
        allowedtypes=OCPP_TYPE,
        fmt="f",
        native_min_value=6,
        native_max_value=32,
        native_step=0.001,
        scale=0.001,
        native_unit_of_measurement=UnitOfElectricCurrent.AMPERE,
        device_class=NumberDeviceClass.CURRENT,
    ),
]

# ================================= Select Declarations ============================================================

SELECT_TYPES = [
    ###
    #
    #  Data only select types
    #
    ###
    ###
    #
    #  Normal select types
    #
    ###
    SolaXEVChargerModbusSelectEntityDescription(
        name="Meter Setting",
        key="meter_setting",
        register=0x60C,
        option_dict={
            0: "External CT",
            1: "External Meter",
            2: "Inverter",
        },
        entity_category=EntityCategory.CONFIG,
        icon="mdi:meter-electric",
    ),
    SolaXEVChargerModbusSelectEntityDescription(
        name="Charger Use Mode",
        key="charger_use_mode",
        register=0x60D,
        option_dict={
            0: "Stop",
            1: "Fast",
            2: "ECO",
            3: "Green",
        },
        icon="mdi:dip-switch",
    ),
    SolaXEVChargerModbusSelectEntityDescription(
        name="ECO Gear",
        key="eco_gear",
        register=0x60E,
        option_dict={
            1: "6A",
            2: "10A",
            3: "16A",
            4: "20A",
            5: "25A",
        },
        entity_category=EntityCategory.CONFIG,
        icon="mdi:dip-switch",
    ),
    SolaXEVChargerModbusSelectEntityDescription(
        name="Green Gear",
        key="green_gear",
        register=0x60F,
        option_dict={
            1: "3A",
            2: "6A",
        },
        entity_category=EntityCategory.CONFIG,
        icon="mdi:dip-switch",
    ),
    SolaXEVChargerModbusSelectEntityDescription(
        name="Start Charge Mode",
        key="start_charge_mode",
        register=0x610,
        allowedtypes=GEN2,
        option_dict={
            0: "Plug and Charge",
            1: "Swipe Card to Start",
            2: "App Start",
        },
        entity_category=EntityCategory.CONFIG,
        icon="mdi:lock",
    ),
    SolaXEVChargerModbusSelectEntityDescription(
        name="Start Charge Mode",
        key="start_charge_mode",
        register=0x610,
        allowedtypes=GEN1,
        option_dict={
            0: "Plug and Charge",
            1: "Swipe Card to Start",
        },
        entity_category=EntityCategory.CONFIG,
        icon="mdi:lock",
    ),
    SolaXEVChargerModbusSelectEntityDescription(
        name="Boost Mode",
        key="boost_mode",
        register=0x613,
        option_dict={
            0: "Normal",
            1: "Timer Boost",
            2: "Smart Boost",
        },
        icon="mdi:dip-switch",
    ),
    SolaXEVChargerModbusSelectEntityDescription(
        name="Charging Mode",
        key="evse_scene",
        register=0x61C,
        allowedtypes=GEN1,
        option_dict={
            0: "Private",
            1: "OCPP",
        },
        entity_category=EntityCategory.CONFIG,
        icon="mdi:dip-switch",
    ),
    SolaXEVChargerModbusSelectEntityDescription(
        name="Charging Mode",
        key="evse_scene",
        register=0x61C,
        allowedtypes=GEN2,
        option_dict={
            0: "PV Mode",
            1: "Standard Mode",
            2: "OCPP Mode",
        },
        entity_category=EntityCategory.CONFIG,
        icon="mdi:dip-switch",
    ),
    SolaXEVChargerModbusSelectEntityDescription(
        name="Charge Phase",
        key="charge_phase",
        register=0x625,
        option_dict={
            0: "Three Phase",
            1: "L1 Phase",
            2: "L2 Phase",
            3: "L3 Phase",
        },
        entity_category=EntityCategory.CONFIG,
        icon="mdi:dip-switch",
        allowedtypes=X3,
    ),
    SolaXEVChargerModbusSelectEntityDescription(
        name="Charge Phase Alt",
        key="charge_phase_alt",
        register=0x63B,
        option_dict={
            0: "Three Phase",
            1: "L1 Phase",
            2: "L2 Phase",
            3: "L3 Phase",
        },
        entity_category=EntityCategory.CONFIG,
        icon="mdi:dip-switch",
        allowedtypes=X3,
        entity_registry_enabled_default=False,
    ),
    SolaXEVChargerModbusSelectEntityDescription(
        name="Control Command",
        key="control_command",
        register=0x627,
        option_dict={
            0: "No Command",
            1: "Available",
            2: "Unavailable",
            3: "Stop Charging",
            4: "Start Charging",
            5: "Reserve",
            6: "Cancel the Reservation",
        },
        icon="mdi:dip-switch",
    ),
    SolaXEVChargerModbusSelectEntityDescription(
        name="EVSE Mode",
        key="evse_mode",
        register=0x669,
        allowedtypes=GEN2,
        option_dict={
            0: "Fast",
            1: "ECO",
            2: "Green",
        },
        entity_category=EntityCategory.CONFIG,
        icon="mdi:dip-switch",
    ),
]

# ================================= Time Declarations ==============================================================

TIME_TYPES = [
    SolaXEVChargerModbusTimeEntityDescription(
        name="Timer Boost Start Time",
        key="timer_boost_start_time",
        register=0x634,
        option_dict=TIME_OPTIONS_SEPARATE_REGISTERS,
        wordcount=2,
        entity_category=EntityCategory.CONFIG,
        icon="mdi:clock-start",
    ),
    SolaXEVChargerModbusTimeEntityDescription(
        name="Timer Boost End Time",
        key="timer_boost_end_time",
        register=0x636,
        option_dict=TIME_OPTIONS_SEPARATE_REGISTERS,
        wordcount=2,
        entity_category=EntityCategory.CONFIG,
        icon="mdi:clock-end",
    ),
    SolaXEVChargerModbusTimeEntityDescription(
        name="Smart Boost End Time",
        key="smart_boost_end_time",
        register=0x638,
        option_dict=TIME_OPTIONS_SEPARATE_REGISTERS,
        wordcount=2,
        entity_category=EntityCategory.CONFIG,
        icon="mdi:clock-end",
    ),
]

# ================================= Sensor Declarations ============================================================


SENSOR_TYPES_MAIN: list[SolaXEVChargerModbusSensorEntityDescription] = [
    ###
    #
    # Holding — internal backing sensors (poll registers for SELECT/NUMBER readback;
    # not registered as HA entities — use the SELECT/NUMBER entities instead)
    #
    ###
    SolaXEVChargerModbusSensorEntityDescription(
        name="Meter Setting",
        key="meter_setting",
        register=0x60C,
        scale={0: "External CT", 1: "External Meter", 2: "Inverter"},
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charger Use Mode",
        key="charger_use_mode",
        register=0x60D,
        scale={0: "Stop", 1: "Fast", 2: "ECO", 3: "Green"},
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="ECO Gear",
        key="eco_gear",
        register=0x60E,
        scale={1: "6A", 2: "10A", 3: "16A", 4: "20A", 5: "25A"},
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Green Gear",
        key="green_gear",
        register=0x60F,
        scale={1: "3A", 2: "6A"},
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Start Charge Mode",
        key="start_charge_mode",
        register=0x610,
        scale={0: "Plug and Charge", 1: "Swipe Card to Start", 2: "App Start"},
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Overload Limit",
        key="overload_limit",
        register=0x611,
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Undervoltage Limit",
        key="undervoltage_limit",
        register=0x612,
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Boost Mode",
        key="boost_mode",
        register=0x613,
        scale={0: "Normal", 1: "Timer Boost", 2: "Smart Boost"},
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Main Breaker Limit",
        key="main_breaker_limit",
        register=0x614,
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Electronic Lock",
        key="electronic_lock",
        register=0x615,
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="RFID Card Activation",
        key="rfid_card_activation",
        register=0x616,
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charging Mode",
        key="evse_scene",
        register=0x61C,
        allowedtypes=GEN1,
        scale={0: "Private", 1: "OCPP"},
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charging Mode",
        key="evse_scene",
        register=0x61C,
        allowedtypes=GEN2,
        scale={0: "PV Mode", 1: "Standard Mode", 2: "OCPP Mode"},
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="RTC",
        key="rtc",
        register=0x61D,
        register_data_type=REGISTER_WORDS,
        wordcount=7,
        scale=value_function_rtc_evc,
        device_class=SensorDeviceClass.TIMESTAMP,
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
        icon="mdi:clock",
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Datahub Charge Current",
        key="datahub_charge_current",
        register=0x624,
        allowedtypes=GEN1,
        scale=0.01,
        rounding=1,
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Phase",
        key="charge_phase",
        register=0x625,
        scale={0: "Three Phase", 1: "L1 Phase", 2: "L2 Phase", 3: "L3 Phase"},
        allowedtypes=X3,
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Phase Alt",
        key="charge_phase_alt",
        register=0x63B,
        scale={0: "Three Phase", 1: "L1 Phase", 2: "L2 Phase", 3: "L3 Phase"},
        allowedtypes=X3,
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Current",
        key="charge_current",
        register=0x628,
        scale=0.01,
        rounding=1,
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Control Command",
        key="control_command",
        register=0x627,
        scale={
            0: "No Command",
            1: "Available",
            2: "Unavailable",
            3: "Stop Charging",
            4: "Start Charging",
            5: "Reserve",
            6: "Cancel the Reservation",
        },
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Max Charge Current",
        key="max_charge_current",
        register=0x668,
        scale=0.01,
        rounding=1,
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="EVSE Mode",
        key="evse_mode",
        register=0x669,
        allowedtypes=GEN2,
        scale={0: "Fast", 1: "ECO", 2: "Green"},
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Modbus Address",
        key="modbus_address",
        register=0x640,
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Timer Boost Start Time",
        key="timer_boost_start_time",
        register=0x634,
        register_data_type=REGISTER_WORDS,
        wordcount=2,
        scale=value_function_separate_registers_time,
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Timer Boost End Time",
        key="timer_boost_end_time",
        register=0x636,
        register_data_type=REGISTER_WORDS,
        wordcount=2,
        scale=value_function_separate_registers_time,
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Smart Boost End Time",
        key="smart_boost_end_time",
        register=0x638,
        register_data_type=REGISTER_WORDS,
        wordcount=2,
        scale=value_function_separate_registers_time,
        internal=True,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Smart Boost Energy",
        key="smart_boost_energy",
        register=0x63A,
        native_unit_of_measurement=UnitOfEnergy.KILO_WATT_HOUR,
        internal=True,
    ),
    ###
    #
    # Input — 0x0100+
    # 0x0100-0x0102: ChargePower L1 (A) / L2 (B) / L3 (C) also available at 0x08-0x0A; exposed here with Alt suffix
    #
    ###
    # ---- 0x0100–0x0102  Phase powers alt for L1 (A) / L2 (B) / L3 (C), disabled by default ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Power L1 Alt",
        key="charge_power_l1_alt",
        register=0x100,
        register_type=REG_INPUT,
        native_unit_of_measurement=UnitOfPower.WATT,
        device_class=SensorDeviceClass.POWER,
        state_class=SensorStateClass.MEASUREMENT,
        entity_registry_enabled_default=False,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Power L2 Alt",
        key="charge_power_l2_alt",
        register=0x101,
        register_type=REG_INPUT,
        allowedtypes=X3,
        native_unit_of_measurement=UnitOfPower.WATT,
        device_class=SensorDeviceClass.POWER,
        state_class=SensorStateClass.MEASUREMENT,
        entity_registry_enabled_default=False,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Power L3 Alt",
        key="charge_power_l3_alt",
        register=0x102,
        register_type=REG_INPUT,
        allowedtypes=X3,
        native_unit_of_measurement=UnitOfPower.WATT,
        device_class=SensorDeviceClass.POWER,
        state_class=SensorStateClass.MEASUREMENT,
        entity_registry_enabled_default=False,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Max Power Charging",
        key="max_power_charging",
        register=0x103,
        register_type=REG_INPUT,
        scale={0: "No", 1: "Yes"},
        entity_category=EntityCategory.DIAGNOSTIC,
        icon="mdi:lightning-bolt",
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Mode Active",
        key="charge_mode_active",
        register=0x104,
        register_type=REG_INPUT,
        scale={0: "Fast", 1: "ECO", 2: "Green"},
        icon="mdi:dip-switch",
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Green Mode Start Power",
        key="green_mode_start_power",
        register=0x105,
        register_type=REG_INPUT,
        native_unit_of_measurement=UnitOfPower.WATT,
        device_class=SensorDeviceClass.POWER,
        state_class=SensorStateClass.MEASUREMENT,
        entity_category=EntityCategory.DIAGNOSTIC,
        icon="mdi:solar-power",
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Run Mode Alt",
        key="charger_status",
        register=0x106,
        register_type=REG_INPUT,
        scale={
            0: "Available",
            1: "Preparing",
            2: "Charging",
            3: "Finishing",
            4: "Faulted",
            5: "Unavailable",
            6: "Reserved",
            7: "Suspended EV",
            8: "Suspended EVSE",
            9: "Update",
            10: "Card Activation",
            11: "Start Delay",
            12: "Charge Paused",
            13: "Stopping",
        },
        entity_registry_enabled_default=False,
        icon="mdi:ev-station",
    ),
    ###
    #
    # Input
    #
    ###
    # ---- 0x0000–0x0002  Phase voltages L1 (A) / L2 (B) / L3 (C), 0.01V ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Voltage",
        key="charge_voltage",
        register=0x0,
        register_type=REG_INPUT,
        scale=0.01,
        native_unit_of_measurement=UnitOfElectricPotential.VOLT,
        device_class=SensorDeviceClass.VOLTAGE,
        allowedtypes=X1,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Voltage L1",
        key="charge_voltage_l1",
        register=0x0,
        register_type=REG_INPUT,
        allowedtypes=X3,
        scale=0.01,
        native_unit_of_measurement=UnitOfElectricPotential.VOLT,
        device_class=SensorDeviceClass.VOLTAGE,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Voltage L2",
        key="charge_voltage_l2",
        register=0x1,
        register_type=REG_INPUT,
        allowedtypes=X3,
        scale=0.01,
        native_unit_of_measurement=UnitOfElectricPotential.VOLT,
        device_class=SensorDeviceClass.VOLTAGE,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Voltage L3",
        key="charge_voltage_l3",
        register=0x2,
        register_type=REG_INPUT,
        allowedtypes=X3,
        scale=0.01,
        native_unit_of_measurement=UnitOfElectricPotential.VOLT,
        device_class=SensorDeviceClass.VOLTAGE,
    ),
    # ---- 0x0003  PE voltage (GEN2 doc: VoltagePE, 0.01V) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge PE Voltage",
        key="charge_pe_voltage",
        register=0x3,
        register_type=REG_INPUT,
        scale=0.01,
        native_unit_of_measurement=UnitOfElectricPotential.VOLT,
        device_class=SensorDeviceClass.VOLTAGE,
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
    ),
    # ---- 0x0004–0x0006  Phase currents L1 (A) / L2 (B) / L3 (C), 0.01A ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Current",
        key="charge_current",
        register=0x4,
        register_type=REG_INPUT,
        scale=0.01,
        native_unit_of_measurement=UnitOfElectricCurrent.AMPERE,
        device_class=SensorDeviceClass.CURRENT,
        allowedtypes=X1,
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Current L1",
        key="charge_current_l1",
        register=0x4,
        register_type=REG_INPUT,
        allowedtypes=X3,
        scale=0.01,
        native_unit_of_measurement=UnitOfElectricCurrent.AMPERE,
        device_class=SensorDeviceClass.CURRENT,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Current L2",
        key="charge_current_l2",
        register=0x5,
        register_type=REG_INPUT,
        allowedtypes=X3,
        scale=0.01,
        native_unit_of_measurement=UnitOfElectricCurrent.AMPERE,
        device_class=SensorDeviceClass.CURRENT,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Current L3",
        key="charge_current_l3",
        register=0x6,
        register_type=REG_INPUT,
        allowedtypes=X3,
        scale=0.01,
        native_unit_of_measurement=UnitOfElectricCurrent.AMPERE,
        device_class=SensorDeviceClass.CURRENT,
    ),
    # ---- 0x0007  PE current (GEN2 doc: CurrentPE, 0.001A) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge PE Current",
        key="charge_pe_current",
        register=0x7,
        register_type=REG_INPUT,
        native_unit_of_measurement=UnitOfElectricCurrent.MILLIAMPERE,
        device_class=SensorDeviceClass.CURRENT,
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
    ),
    # ---- 0x0008–0x000A  Phase powers L1 (A) / L2 (B) / L3 (C), 1W ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Power",
        key="charge_power",
        register=0x8,
        register_type=REG_INPUT,
        native_unit_of_measurement=UnitOfPower.WATT,
        device_class=SensorDeviceClass.POWER,
        state_class=SensorStateClass.MEASUREMENT,
        allowedtypes=X1,
        entity_registry_enabled_default=False,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Power L1",
        key="charge_power_l1",
        register=0x8,
        register_type=REG_INPUT,
        allowedtypes=X3,
        native_unit_of_measurement=UnitOfPower.WATT,
        device_class=SensorDeviceClass.POWER,
        state_class=SensorStateClass.MEASUREMENT,
        entity_registry_enabled_default=False,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Power L2",
        key="charge_power_l2",
        register=0x9,
        register_type=REG_INPUT,
        allowedtypes=X3,
        native_unit_of_measurement=UnitOfPower.WATT,
        device_class=SensorDeviceClass.POWER,
        state_class=SensorStateClass.MEASUREMENT,
        entity_registry_enabled_default=False,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Power L3",
        key="charge_power_l3",
        register=0xA,
        register_type=REG_INPUT,
        allowedtypes=X3,
        native_unit_of_measurement=UnitOfPower.WATT,
        device_class=SensorDeviceClass.POWER,
        state_class=SensorStateClass.MEASUREMENT,
        entity_registry_enabled_default=False,
    ),
    # ---- 0x000B  Total charge power (GEN2 doc: TotalChargePower, 1W) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Power Total",
        key="charge_power_total",
        register=0xB,
        register_type=REG_INPUT,
        native_unit_of_measurement=UnitOfPower.WATT,
        device_class=SensorDeviceClass.POWER,
        state_class=SensorStateClass.MEASUREMENT,
    ),
    # ---- 0x000C–0x000E  Phase frequencies L1 (A) / L2 (B) / L3 (C), 0.01Hz ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Frequency",
        key="charge_frequency",
        register=0xC,
        register_type=REG_INPUT,
        scale=0.01,
        native_unit_of_measurement=UnitOfFrequency.HERTZ,
        allowedtypes=X1,
        entity_registry_enabled_default=False,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Frequency L1",
        key="charge_frequency_l1",
        register=0xC,
        register_type=REG_INPUT,
        allowedtypes=X3,
        scale=0.01,
        native_unit_of_measurement=UnitOfFrequency.HERTZ,
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Frequency L2",
        key="charge_frequency_l2",
        register=0xD,
        register_type=REG_INPUT,
        allowedtypes=X3,
        scale=0.01,
        native_unit_of_measurement=UnitOfFrequency.HERTZ,
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Frequency L3",
        key="charge_frequency_l3",
        register=0xE,
        register_type=REG_INPUT,
        allowedtypes=X3,
        scale=0.01,
        native_unit_of_measurement=UnitOfFrequency.HERTZ,
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
    ),
    # ---- 0x000F  Session energy (GEN2 doc: EQ_Single, 0.1kWh) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Added",
        key="charge_added",
        register=0xF,
        register_type=REG_INPUT,
        scale=0.1,
        native_unit_of_measurement=UnitOfEnergy.KILO_WATT_HOUR,
        device_class=SensorDeviceClass.ENERGY,
        state_class=SensorStateClass.TOTAL_INCREASING,
    ),
    # ---- 0x0010  Cumulative energy u32 (GEN2 doc: EQ_Total, 0.1kWh) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Added - Cumulative",
        key="charge_added_cum",
        register=0x10,
        register_type=REG_INPUT,
        register_data_type=REGISTER_U32,
        order32="big",
        allowedtypes=GEN1,
        scale=0.1,
        native_unit_of_measurement=UnitOfEnergy.KILO_WATT_HOUR,
        device_class=SensorDeviceClass.ENERGY,
        state_class=SensorStateClass.TOTAL_INCREASING,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Added - Cumulative",
        key="charge_added_cum",
        register=0x10,
        register_type=REG_INPUT,
        register_data_type=REGISTER_U32,
        allowedtypes=GEN2 | GEN3 | GEN4,
        scale=0.1,
        native_unit_of_measurement=UnitOfEnergy.KILO_WATT_HOUR,
        device_class=SensorDeviceClass.ENERGY,
        state_class=SensorStateClass.TOTAL_INCREASING,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charge Added Total",
        key="charge_added_total",
        register=0x619,
        register_type=REG_HOLDING,
        register_data_type=REGISTER_U32,
        scale=0.1,
        native_unit_of_measurement=UnitOfEnergy.KILO_WATT_HOUR,
        device_class=SensorDeviceClass.ENERGY,
        state_class=SensorStateClass.TOTAL_INCREASING,
    ),
    # ---- 0x0012–0x0014  Grid currents L1 (A) / L2 (B) / L3 (C), S16, 0.01A ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Grid Current",
        key="grid_current",
        register=0x12,
        register_type=REG_INPUT,
        register_data_type=REGISTER_S16,
        scale=0.01,
        native_unit_of_measurement=UnitOfElectricCurrent.AMPERE,
        device_class=SensorDeviceClass.CURRENT,
        allowedtypes=X1,
        entity_registry_enabled_default=False,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Grid Current L1",
        key="grid_current_l1",
        register=0x12,
        register_type=REG_INPUT,
        register_data_type=REGISTER_S16,
        allowedtypes=X3,
        scale=0.01,
        native_unit_of_measurement=UnitOfElectricCurrent.AMPERE,
        device_class=SensorDeviceClass.CURRENT,
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Grid Current L2",
        key="grid_current_l2",
        register=0x13,
        register_type=REG_INPUT,
        register_data_type=REGISTER_S16,
        allowedtypes=X3,
        scale=0.01,
        native_unit_of_measurement=UnitOfElectricCurrent.AMPERE,
        device_class=SensorDeviceClass.CURRENT,
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Grid Current L3",
        key="grid_current_l3",
        register=0x14,
        register_type=REG_INPUT,
        register_data_type=REGISTER_S16,
        allowedtypes=X3,
        scale=0.01,
        native_unit_of_measurement=UnitOfElectricCurrent.AMPERE,
        device_class=SensorDeviceClass.CURRENT,
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
    ),
    # ---- 0x0015–0x0017  Grid powers L1 (A) / L2 (B) / L3 (C), S16, 1W ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Grid Power",
        key="grid_power",
        register=0x15,
        register_type=REG_INPUT,
        register_data_type=REGISTER_S16,
        native_unit_of_measurement=UnitOfPower.WATT,
        device_class=SensorDeviceClass.POWER,
        state_class=SensorStateClass.MEASUREMENT,
        allowedtypes=X1,
        entity_registry_enabled_default=False,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Grid Power L1",
        key="grid_power_l1",
        register=0x15,
        register_type=REG_INPUT,
        register_data_type=REGISTER_S16,
        allowedtypes=X3,
        native_unit_of_measurement=UnitOfPower.WATT,
        device_class=SensorDeviceClass.POWER,
        state_class=SensorStateClass.MEASUREMENT,
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Grid Power L2",
        key="grid_power_l2",
        register=0x16,
        register_type=REG_INPUT,
        register_data_type=REGISTER_S16,
        allowedtypes=X3,
        native_unit_of_measurement=UnitOfPower.WATT,
        device_class=SensorDeviceClass.POWER,
        state_class=SensorStateClass.MEASUREMENT,
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Grid Power L3",
        key="grid_power_l3",
        register=0x17,
        register_type=REG_INPUT,
        register_data_type=REGISTER_S16,
        allowedtypes=X3,
        native_unit_of_measurement=UnitOfPower.WATT,
        device_class=SensorDeviceClass.POWER,
        state_class=SensorStateClass.MEASUREMENT,
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
    ),
    # ---- 0x0018  Total grid power S16 (GEN2 doc: ExternTotalPower, 1W) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Grid Power Total",
        key="grid_power_total",
        register=0x18,
        register_type=REG_INPUT,
        register_data_type=REGISTER_S16,
        native_unit_of_measurement=UnitOfPower.WATT,
        device_class=SensorDeviceClass.POWER,
        state_class=SensorStateClass.MEASUREMENT,
    ),
    # ---- 0x0019–0x001C  Not in GEN2 doc; present in GEN1 doc and live on device ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="CC Voltage",
        key="cc_voltage",
        register=0x19,
        register_type=REG_INPUT,
        scale=0.1,
        native_unit_of_measurement=UnitOfElectricPotential.VOLT,
        device_class=SensorDeviceClass.VOLTAGE,
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
        icon="mdi:sine-wave",
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="CP Voltage",
        key="cp_voltage",
        register=0x1A,
        register_type=REG_INPUT,
        scale=0.01,
        native_unit_of_measurement=UnitOfElectricPotential.VOLT,
        device_class=SensorDeviceClass.VOLTAGE,
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
        icon="mdi:sine-wave",
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="PWM Duty Cycle",
        key="pwm_duty_cycle",
        register=0x1B,
        register_type=REG_INPUT,
        scale=0.1,
        native_unit_of_measurement=PERCENTAGE,
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
        icon="mdi:pulse",
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charger Temperature",
        key="charger_temperature",
        register=0x1C,
        register_type=REG_INPUT,
        native_unit_of_measurement=UnitOfTemperature.CELSIUS,
        device_class=SensorDeviceClass.TEMPERATURE,
        state_class=SensorStateClass.MEASUREMENT,
        entity_category=EntityCategory.DIAGNOSTIC,
    ),
    # ---- 0x001D  EVSE state (GEN2 doc: EVSE_State, 0–13) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Run Mode",
        key="run_mode",
        register=0x1D,
        register_type=REG_INPUT,
        scale={
            0: "Available",
            1: "Preparing",
            2: "Charging",
            3: "Finishing",
            4: "Faulted",
            5: "Unavailable",
            6: "Reserved",
            7: "Suspended EV",
            8: "Suspended EVSE",
            9: "Update",
            10: "Card Activation",
            11: "Start Delay",
            12: "Charge Paused",
            13: "Stopping",
        },
        icon="mdi:ev-station",
    ),
    # ---- 0x001E  Fault code u32 (GEN2 doc: FaultCode) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Fault Code",
        key="fault_code",
        register=0x1E,
        register_type=REG_INPUT,
        register_data_type=REGISTER_U32,
        entity_category=EntityCategory.DIAGNOSTIC,
        icon="mdi:alert",
    ),
    # ---- 0x0020  Cable type (GEN2 doc: TypeCase, 0=CaseB, 1=CaseC) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Case Type",
        key="case_type",
        register=0x20,
        register_type=REG_INPUT,
        scale={
            0: "Case B",
            1: "Case C",
        },
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
        icon="mdi:ev-plug-type2",
    ),
    # ---- 0x0021  Power rating ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Power Rating",
        key="power_rating",
        register=0x21,
        register_type=REG_INPUT,
        scale={
            0: "7.2 kW",
            1: "11 kW",
            2: "22 kW",
            3: "4.6 kW",
        },
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
        icon="mdi:lightning-bolt",
    ),
    # ---- 0x0022  Phase count (GEN2 doc: TypePhase, 0=Single, 1=Three) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Phase Type",
        key="phase_type",
        register=0x22,
        register_type=REG_INPUT,
        scale={
            0: "Single Phase",
            1: "Three Phase",
        },
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
        icon="mdi:sine-wave",
    ),
    # ---- 0x0023  GEN1: TypeCharger (0=Home, 1=OCPP) / GEN2: EVSE_Scene (0=PV,1=Standard,2=OCPP) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charger Type",
        key="model_type",
        register=0x23,
        register_type=REG_INPUT,
        allowedtypes=GEN1,
        scale={
            0: "Home",
            1: "OCPP",
        },
        entity_category=EntityCategory.DIAGNOSTIC,
        icon="mdi:dip-switch",
    ),
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charging Scene",
        key="model_type",
        register=0x23,
        register_type=REG_INPUT,
        allowedtypes=GEN2,
        scale={
            0: "PV Mode",
            1: "Standard Mode",
            2: "OCPP Mode",
        },
        entity_category=EntityCategory.DIAGNOSTIC,
        icon="mdi:dip-switch",
    ),
    # ---- 0x0024  Screen fitted (GEN1 doc only; not in GEN2 doc but present on device) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Screen Fitted",
        key="screen_fitted",
        register=0x24,
        register_type=REG_INPUT,
        scale={
            0: "No",
            1: "Yes",
        },
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
        icon="mdi:monitor",
    ),
    # ---- 0x0025  Firmware version (GEN2 doc: FirmwareVersion) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Firmware Version",
        key="firmware_version",
        register=0x25,
        register_type=REG_INPUT,
        register_data_type=REGISTER_U16,
        scale=value_function_firmware_decimal_hundredths,
        entity_category=EntityCategory.DIAGNOSTIC,
        icon="mdi:numeric",
    ),
    # ---- 0x0026  OCPP Network (0=Not Connected, 1=Connected) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="OCPP Network",
        key="net_connected",
        register=0x26,
        register_type=REG_INPUT,
        allowedtypes=OCPP_TYPE,
        scale={
            0: "Not Connected",
            1: "Connected",
        },
        entity_category=EntityCategory.DIAGNOSTIC,
        icon="mdi:wifi",
    ),
    # ---- 0x0027  Signal strength (GEN2 doc: RSSI, 1%) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="RSSI",
        key="rssi",
        register=0x27,
        register_type=REG_INPUT,
        native_unit_of_measurement=PERCENTAGE,
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
        icon="mdi:wifi-strength-2",
    ),
    # ---- 0x0028  Active charge phase (GEN2 doc: ChargePhase) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Active Charge Phase",
        key="active_charge_phase",
        register=0x28,
        register_type=REG_INPUT,
        scale={
            0: "Three Phase",
            1: "L1 Phase",
            2: "L2 Phase",
            3: "L3 Phase",
        },
        icon="mdi:cable-data",
    ),
    # ---- 0x0029  Unbalanced power (GEN2 doc: UnbalancedPower, 1W) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Unbalanced Power Limit",
        key="unbalanced_power_limit",
        register=0x29,
        register_type=REG_INPUT,
        native_unit_of_measurement=UnitOfPower.WATT,
        device_class=SensorDeviceClass.POWER,
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
        icon="mdi:scale-unbalanced",
    ),
    # ---- 0x002A  Unbalanced switch (GEN2 doc: UnbalancedSwitch, 0=Off, 1=On) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Phase Unbalance",
        key="phase_unbalance",
        register=0x2A,
        register_type=REG_INPUT,
        scale={
            0: "Off",
            1: "On",
        },
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
        icon="mdi:scale-unbalanced",
    ),
    # ---- 0x002B  Charging duration u32 (GEN2 doc: Charging_time, 1s) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Charging Duration",
        key="charge_duration",
        register=0x2B,
        register_type=REG_INPUT,
        register_data_type=REGISTER_U32,
        device_class=SensorDeviceClass.DURATION,
        state_class=SensorStateClass.TOTAL,
        native_unit_of_measurement=UnitOfTime.SECONDS,
        suggested_display_precision=0,
        icon="mdi:timer",
    ),
    # ---- 0x002D  Lock status (GEN2 doc: Lock_Status, 0=Unlocked, 1=Locked) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Lock State",
        key="lock_state",
        register=0x2D,
        register_type=REG_INPUT,
        scale={
            0: "Unlocked",
            1: "Locked",
        },
        icon="mdi:lock",
    ),
    # ---- 0x002E  Main breaker limit (GEN2 doc: MainBreakerLimitState) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Main Breaker Limit State",
        key="mainbrk_limit",
        register=0x2E,
        register_type=REG_INPUT,
        scale={
            0: "Not Limited",
            1: "Limited, Charging",
            2: "Stopped Charging",
        },
        icon="mdi:car-speed-limiter",
    ),
    # ---- 0x002F  Delay state (GEN2 doc: delay_state, 0=Not in Delay, 1=In Delay) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Random Delay State",
        key="delay_state",
        register=0x2F,
        register_type=REG_INPUT,
        scale={
            0: "Not in Delay",
            1: "In Random Delay",
        },
        entity_registry_enabled_default=False,
        entity_category=EntityCategory.DIAGNOSTIC,
        icon="mdi:progress-clock",
    ),
    # ---- 0x0030  Ban state (GEN2 doc: ban_state, 0=None, 1=Prohibited) ----
    SolaXEVChargerModbusSensorEntityDescription(
        name="Ban State",
        key="ban_state",
        register=0x30,
        register_type=REG_INPUT,
        scale={
            0: "Okay",
            1: "Charge Prohibited",
        },
        icon="mdi:hand-back-left",
    ),
]

# ============================ plugin declaration =================================================


@dataclass(kw_only=True)
class solax_ev_charger_plugin(plugin_base):
    '''
    def isAwake(self, datadict: dict[str, Any]) -> bool:
        """ determine if inverter is awake based on polled datadict"""
        return (datadict.get('run_mode', None) == 'Normal Mode')

    def wakeupButton(self) -> str:
        """ in order to wake up  the inverter , press this button """
        return 'battery_awaken'
    '''

    async def async_determineInverterType(self, hub: Any, configdict: dict[str, Any]) -> int:
        _LOGGER.info(f"{hub.name}: trying to determine inverter type")
        _LOGGER.debug(f"{hub.name}: Reading serial number to determine inverter type")
        seriesnumber = await async_read_serialnr(hub, 0x600)
        _LOGGER.debug(f"{hub.name}: Received serial number: {seriesnumber}")
        if not seriesnumber:
            _LOGGER.error(f"{hub.name}: cannot find serial number for EV Charger")
            seriesnumber = "unknown"

        # derive invertertupe from seriesnumber
        _LOGGER.debug(f"{hub.name}: Determining inverter type from serial number prefix")
        invertertype = 0
        self.inverter_model = None
        if seriesnumber.startswith("C107"):
            invertertype = X1 | POW7 | GEN1  # 7kW EV Single Phase Gen1 (X1-EVC-7kW*)
            self.inverter_model = "X1-EVC-7kW"
            self.hardware_version = "Gen1"
            _LOGGER.debug(
                f"{hub.name}: Matched C107 - X1 | POW7 | GEN1 (7kW EV Single Phase Gen1), type=0x{invertertype:x}, model={self.inverter_model}, hw={self.hardware_version}"
            )
        elif seriesnumber.startswith("C311"):
            # Default to GEN1 for backward compatibility
            _LOGGER.debug(f"{hub.name}: C311 series number detected: {seriesnumber}")
            invertertype = X3 | POW11 | GEN1  # 11kW EV Three Phase Gen1 (X3-EVC-11kW*)
            self.inverter_model = "X3-EVC-11kW"
            _LOGGER.debug(f"{hub.name}: C311 model set to: {self.inverter_model}")
            self.hardware_version = "Gen1"

            # Try to detect GEN2 firmware for hybrid hardware
            fw_version = await async_read_firmware(hub, 0x25)
            if fw_version is not None and fw_version >= 7.0:
                # Upgrade to GEN2 - has GEN2 firmware
                invertertype = X3 | POW11 | GEN2
                self.hardware_version = "Gen1 (GEN2 FW)"
                _LOGGER.info(f"{hub.name}: C311 detected with GEN2 firmware v{fw_version:.2f}, enabling GEN2 features")

            _LOGGER.debug(f"{hub.name}: Matched C311 - X3 | POW11 | type=0x{invertertype:x}, model={self.inverter_model}, hw={self.hardware_version}")
        elif seriesnumber.startswith("C322"):
            # Default to GEN1 for backward compatibility
            _LOGGER.debug(f"{hub.name}: C322 series number detected: {seriesnumber}")
            invertertype = X3 | POW22 | GEN1  # 22kW EV Three Phase Gen1 (X3-EVC-22kW*)
            self.inverter_model = "X3-EVC-22kW"
            _LOGGER.debug(f"{hub.name}: C322 model set to: {self.inverter_model}")
            self.hardware_version = "Gen1"

            # Try to detect GEN2 firmware for hybrid hardware
            fw_version = await async_read_firmware(hub, 0x25)
            if fw_version is not None and fw_version >= 7.0:
                # Upgrade to GEN2 - has GEN2 firmware
                invertertype = X3 | POW22 | GEN2
                self.hardware_version = "Gen1 (GEN2 FW)"
                _LOGGER.info(f"{hub.name}: C322 detected with GEN2 firmware v{fw_version:.2f}, enabling GEN2 features")

            _LOGGER.debug(f"{hub.name}: Matched C322 - X3 | POW22 | type=0x{invertertype:x}, model={self.inverter_model}, hw={self.hardware_version}")
        elif len(seriesnumber) >= 5 and seriesnumber.startswith("5"):
            model_code = seriesnumber[1:3]
            power_code = seriesnumber[3:5]

            model_map = {
                "02": ("X1-HAC", X1),
                "03": ("X3-HAC", X3),
                "04": ("A1-HAC", X1),
                "05": ("J1-HAC", X1),
                "06": ("X1-HAC-S", X1),
                "07": ("X3-HAC-S", X3),
                "08": ("C1-HAC", X1),
                "09": ("C3-HAC", X3),
            }

            power_map = {
                "04": ("4.6kW", POW4),
                "07": ("7.2kW", POW7),
                "0B": ("11kW", POW11),
                "0M": ("22kW", POW22),
            }

            model_info = model_map.get(model_code)
            power_info = power_map.get(power_code)
            if model_info and power_info:
                model_prefix, phase_mask = model_info
                power_label, power_mask = power_info
                invertertype = phase_mask | power_mask | GEN2
                self.inverter_model = f"{model_prefix} {power_label}"
                self.hardware_version = "Gen2"
                _LOGGER.debug(
                    f"{hub.name}: Parsed serial codes model={model_code} power={power_code} -> "
                    f"type=0x{invertertype:x}, model={self.inverter_model}, hw={self.hardware_version}"
                )
        # add cases here

        if invertertype == 0:
            _LOGGER.error(f"unrecognized inverter type - serial number : {seriesnumber}")
            _LOGGER.debug(f"{hub.name}: No match found for serial number prefix, returning type=0")

        # Detect OCPP via 0x0023 — meaning differs by generation:
        # GEN1: TypeCharger (static hardware type); value 1 = OCPP variant.
        # GEN2: EVSE_Scene (current mode); value 2 = OCPP Mode.
        # Note: on GEN2 this reflects the mode at HA startup. OCPP entities appear
        # only when the device is in OCPP mode when HA starts; a restart is required
        # if the mode is changed. This is intentional — consistent with how all
        # allowedtypes flags work in this integration.
        try:
            type_data = await hub.async_read_input_registers(unit=hub._modbus_addr, address=0x0023, count=1)
            if not type_data.isError():
                val = type_data.registers[0]
                ocpp_detected = (invertertype & GEN1 and val == 1) or (invertertype & GEN2 and val == 2)
                if ocpp_detected:
                    invertertype |= OCPP_TYPE
                    _LOGGER.info(f"{hub.name}: OCPP detected (0x0023={val})")
                else:
                    _LOGGER.debug(f"{hub.name}: OCPP not active (0x0023={val})")
            else:
                _LOGGER.debug(f"{hub.name}: Could not read 0x0023 for OCPP probe (Modbus error)")
        except Exception:
            _LOGGER.debug(f"{hub.name}: Could not read charger type register 0x0023", exc_info=True)

        _LOGGER.debug(f"{hub.name}: Final inverter type determination: 0x{invertertype:x}, model={self.inverter_model}")
        return invertertype

    def matchInverterWithMask(
        self,
        inverterspec: Any,
        entitymask: Any,
        serialnumber: str = "not relevant",
        blacklist: list[str] | None = None,
    ) -> bool:
        # returns true if the entity needs to be created for an inverter
        _LOGGER.debug(f"matchInverterWithMask: inverterspec=0x{inverterspec:x}, entitymask=0x{entitymask:x}, serialnumber={serialnumber}")
        powmatch = ((inverterspec & entitymask & ALL_POW_GROUP) != 0) or (entitymask & ALL_POW_GROUP == 0)
        xmatch = ((inverterspec & entitymask & ALL_X_GROUP) != 0) or (entitymask & ALL_X_GROUP == 0)
        genmatch = ((inverterspec & entitymask & ALL_GEN_GROUP) != 0) or (entitymask & ALL_GEN_GROUP == 0)
        featurematch = ((inverterspec & entitymask & ALL_FEATURE_GROUP) != 0) or (entitymask & ALL_FEATURE_GROUP == 0)
        _LOGGER.debug(f"matchInverterWithMask: powmatch={powmatch}, xmatch={xmatch}, genmatch={genmatch}, featurematch={featurematch}")
        blacklisted = False
        if blacklist:
            _LOGGER.debug(f"matchInverterWithMask: Checking blacklist: {blacklist}")
            for start in blacklist:
                if serialnumber.startswith(start):
                    blacklisted = True
                    _LOGGER.debug(f"matchInverterWithMask: Serial number {serialnumber} matches blacklist prefix {start}")
        result = (xmatch and powmatch and genmatch and featurematch) and not blacklisted
        _LOGGER.debug(f"matchInverterWithMask: Final result: {result} (blacklisted={blacklisted})")
        return result

    def getModel(self, new_data: dict[str, Any]) -> str | None:
        return getattr(self, "inverter_model", None)

    def getSoftwareVersion(self, new_data: dict[str, Any]) -> str | None:
        fw = new_data.get("firmware_version")
        return f"ARM v{fw}" if fw is not None else None

    def getHardwareVersion(self, new_data: dict[str, Any]) -> str | None:
        return getattr(self, "hardware_version", None)


plugin_instance = solax_ev_charger_plugin(
    plugin_name="SolaX EV Charger",
    plugin_manufacturer="SolaX Power",
    SENSOR_TYPES=SENSOR_TYPES_MAIN,
    NUMBER_TYPES=NUMBER_TYPES,
    BUTTON_TYPES=BUTTON_TYPES,
    SELECT_TYPES=SELECT_TYPES,
    SWITCH_TYPES=[
        BaseModbusSwitchEntityDescription(
            name="Electronic Lock",
            key="electronic_lock",
            register=0x615,
            sensor_key="electronic_lock",
            value_function=value_function_enable_disable,
            entity_category=EntityCategory.CONFIG,
            icon="mdi:lock",
        ),
        BaseModbusSwitchEntityDescription(
            name="RFID Card Activation",
            key="rfid_card_activation",
            register=0x616,
            sensor_key="rfid_card_activation",
            value_function=value_function_enable_disable,
            entity_category=EntityCategory.CONFIG,
            icon="mdi:card-account-details",
        ),
    ],
    TIME_TYPES=TIME_TYPES,
    block_size=32,
    # order16=Endian.BIG,
    order32="little",
)