### Example Usage of async_setup_entry

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/sensor-platform.md

Demonstrates how to call the async_setup_entry function within a Home Assistant setup context. Requires importing AddEntitiesCallback and getting the current HASS instance and config entry.

```python
from homeassistant.helpers.entity_platform import AddEntitiesCallback

async def setup_sensors():
    hass = get_current_hass()
    config_entry = hass.config_entries.async_get_entry("entry_id")
    
    def add_entities(entities):
        # Home Assistant will call this with sensor entities
        pass
    
    await async_setup_entry(hass, config_entry, add_entities)
```

--------------------------------

### Setup Example with SmaEvChargerConfigEntry

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/data-structures.md

Illustrates the use of the SmaEvChargerConfigEntry type hint in an async setup function. This ensures that the runtime_data attribute is correctly typed, providing access to the coordinator and evcharger objects.

```python
from homeassistant.core import HomeAssistant

async def async_setup_entry(
    hass: HomeAssistant,
    entry: SmaEvChargerConfigEntry
) -> bool:
    """Setup requires SmaEvChargerConfigEntry type."""
    # entry.runtime_data is known to be SmaEvChargerRuntimeData
    coordinator = entry.runtime_data.coordinator
    evcharger = entry.runtime_data.evcharger
    # Type checking ensures these are available
```

--------------------------------

### Initialize SmaEvChargerCoordinator Example

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/coordinator.md

Example demonstrating how to initialize the SmaEvChargerCoordinator. Requires Home Assistant instance, configuration entry, and a pysmaev SmaEvCharger instance.

```python
from custom_components.smaev.coordinator import SmaEvChargerCoordinator
import pysmaev.core

hass = get_current_hass()
entry = hass.config_entries.async_get_entry("entry_id")
e charger = pysmaev.core.SmaEvCharger(session, url, username, password)

coordinator = SmaEvChargerCoordinator(hass, entry, evcharger)
```

--------------------------------

### Example Device Configuration

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/configuration.md

Illustrates the configuration data stored internally by the integration, not directly in `configuration.yaml`.

```yaml
# Configuration stored internally by integration
# Not in configuration.yaml
{
    "host": "192.168.1.100",
    "username": "installer",
    "password": "my_secure_password",
    "ssl": true,
    "verify_ssl": false
}
```

--------------------------------

### Retrieve Coordinator by Device ID Example

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/coordinator.md

Example of using the async_get_coordinator_by_device_id function to get a coordinator instance using a device ID. Handles potential ValueError if the device or coordinator is not found.

```python
from custom_components.smaev.coordinator import async_get_coordinator_by_device_id

device_id = "charger_device_123"
try:
    coordinator = async_get_coordinator_by_device_id(hass, device_id)
    # Use coordinator for operations
except ValueError as e:
    # Handle error
    pass
```

--------------------------------

### Example Service Call for Restart

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/constants.md

Demonstrates how to asynchronously call the 'restart' service for a specific device ID.

```python
await hass.services.async_call(
    "smaev",
    SERVICE_RESTART,
    {"device_id": "charger_device_id"}
)
```

--------------------------------

### Public API Setup Entry Points

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/README.md

Functions for setting up and unloading Home Assistant integration entries.

```python
# Setup entry points
async def async_setup_entry(hass: HomeAssistant, entry: SmaEvChargerConfigEntry) -> bool
async def async_unload_entry(hass: Home Assistant, entry: SmaEvChargerConfigEntry) -> bool
```

--------------------------------

### Public API Services Setup

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/README.md

Functions for setting up and unloading integration services.

```python
# Services
def async_setup_services(hass: HomeAssistant) -> None
def async_unload_services(hass: Home Assistant) -> None
```

--------------------------------

### Manually Call _async_update_data Example

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/coordinator.md

Example of manually calling the _async_update_data method on the coordinator and handling potential UpdateFailed errors.

```python
coordinator = SmaEvChargerCoordinator(hass, entry, evcharger)
# Called automatically on the configured interval
# But can also be called manually:
try:
    data = await coordinator._async_update_data()
    measurements = data["measurement"]
    parameters = data["parameter"]
except UpdateFailed as e:
    # Handle update failure
    pass
```

--------------------------------

### Async Step User Function Signature

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/config-flow.md

Handles the initial configuration step for a new device setup. It takes user input and returns a configuration flow result.

```python
async def async_step_user(
    self, 
    user_input: dict[str, Any] | None = None
) -> ConfigFlowResult
```

--------------------------------

### Setup SMA EV Charger Services

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/services-and-actions.md

Registers all integration services, including the 'smaev.restart' service. This function is typically called during Home Assistant's setup process.

```python
from homeassistant.core import HomeAssistant
from custom_components.smaev.services import async_setup_services

hass = get_current_hass()
async_setup_services(hass)
# Services are now available
```

--------------------------------

### Runtime Options Configuration

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/overview.md

Shows an example of runtime options for the integration, specifically setting the scan interval in seconds. This highlights user-configurable settings that can be managed.

```python
entry.options = {
    "scan_interval": 5  # seconds
}
```

--------------------------------

### async_setup_entry

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/setup-functions.md

Core integration entry point that initializes SMA EV Charger configuration and sets up all entities. It handles the initial connection, device information retrieval, and entity platform setup.

```APIDOC
## async_setup_entry()

### Description
Core integration entry point that initializes SMA EV Charger configuration and sets up all entities. It handles the initial connection, device information retrieval, and entity platform setup.

### Method
`async def async_setup_entry(hass: HomeAssistant, entry: SmaEvChargerConfigEntry) -> bool`

### Parameters
#### Path Parameters
- **hass** (HomeAssistant) - Required - Home Assistant instance
- **entry** (SmaEvChargerConfigEntry) - Required - Configuration entry with connection data

### Returns
`bool` — True if setup successful, raises exception on failure

### Throws
- `ConfigEntryNotReady` — Device connection cannot be established
- `ConfigEntryAuthFailed` — Authentication credentials are invalid
- `SmaEvChargerConnectionError` — Network connectivity issue with device
- `SmaEvChargerAuthenticationError` — Invalid credentials provided

### Behavior
1. Constructs protocol and URL from config entry (HTTP/HTTPS)
2. Creates aiohttp session with optional SSL verification
3. Instantiates `pysmaev.core.SmaEvCharger` with credentials
4. Connects to device and retrieves device_info
5. Creates device registry entry with manufacturer, model, serial, firmware version
6. Fetches available measurement and parameter channels
7. Creates and assigns `SmaEvChargerCoordinator` for periodic data updates
8. Stores runtime data in config entry
9. Sets up entity platforms: datetime, number, select, sensor, switch
10. Registers integration-wide services

### Request Example
```python
# Within Home Assistant config flow or automated setup
hass = get_current_hass()
entry = ConfigEntry(
    domain="smaev",
    data={
        "host": "192.168.1.100",
        "username": "installer",
        "password": "password",
        "ssl": True,
        "verify_ssl": False
    },
    ...
)
success = await async_setup_entry(hass, entry)
if success:
    # Integration loaded successfully
    # All entities now available
    pass
```

### Source
`custom_components/smaev/__init__.py:58-109`
```

--------------------------------

### Core Functions

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/README.md

Provides documentation for core setup and utility functions used within the integration.

```APIDOC
## Core Functions

### `async_setup_entry()`

#### Description
Initializes the integration for a given configuration entry.

### `async_unload_entry()`

#### Description
Cleans up and unloads the integration from a configuration entry.

### `generate_smaev_entity_id()`

#### Description
Generates a unique entity ID for SMA EV Charger devices.
```

--------------------------------

### Example SmaEvChargerSensor Instantiation

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/sensor-platform.md

Demonstrates how to create an instance of SmaEvChargerSensor with a specific entity description for charging session energy. Ensure all necessary imports are present.

```python
from custom_components.smaev.sensor import SmaEvChargerSensor, SmaEvChargerSensorEntityDescription
from homeassistant.components.sensor import SensorDeviceClass, SensorStateClass
from homeassistant.const import UnitOfEnergy

description = SmaEvChargerSensorEntityDescription(
    key="charging_session_energy",
    translation_key="charging_session_energy",
    type="measurement",
    channel="Measurement.ChaSess.WhIn",
    device_class=SensorDeviceClass.ENERGY,
    state_class=SensorStateClass.TOTAL_INCREASING,
    native_unit_of_measurement=UnitOfEnergy.WATT_HOUR,
)

sensor = SmaEvChargerSensor(
    hass,
    config_entry,
    device_info,
    description
)
```

--------------------------------

### Handle pysmaev Authentication Error during Device Open

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/errors.md

This example shows how to catch a pysmaev authentication error when opening the EV charger and convert it into a ConfigEntryAuthFailed exception. This is typically done during the initial setup phase.

```python
try:
    await evcharger.open()
except pysmaev.exceptions.SmaEvChargerAuthenticationError:
    # Credentials invalid - stop and notify user
    raise ConfigEntryAuthFailed
```

--------------------------------

### SmaEvChargerNumber Example Initialization

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/number-platform.md

Demonstrates how to create an instance of SmaEvChargerNumber with specific configuration for a 'standby_charge_disconnect' entity.

```python
from custom_components.smaev.number import SmaEvChargerNumber, SmaEvChargerNumberEntityDescription
from homeassistant.components.number import NumberMode
from homeassistant.const import UnitOfTime

# Assume hass, config_entry, and device_info are defined elsewhere

description = SmaEvChargerNumberEntityDescription(
    key="standby_charge_disconnect",
    translation_key="standby_charge_disconnect",
    type="parameter",
    channel="Parameter.Chrg.StpWhenFlTm",
    native_step=1,
    mode=NumberMode.BOX,
    native_unit_of_measurement=UnitOfTime.MINUTES,
)

number = SmaEvChargerNumber(
    hass,
    config_entry,
    device_info,
    description
)
```

--------------------------------

### Instantiate SmaEvChargerSelect

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/select-platform.md

Example of creating a SmaEvChargerSelect instance with a specific entity description.

```python
from custom_components.smaev.select import SmaEvChargerSelect, SmaEvChargerSelectEntityDescription
from pysmaev.const import SmaEvChargerParameters

description = SmaEvChargerSelectEntityDescription(
    key="operating_mode_of_charge_session",
    translation_key="operating_mode_of_charge_session",
    type="parameter",
    channel="Parameter.Chrg.ActChaMod",
    value_mapping={
        SmaEvChargerParameters.BOOST_CHARGING: "boost_charging",
        SmaEvChargerParameters.OPTIMIZED_CHARGING: "optimized_charging",
        SmaEvChargerParameters.SETPOINT_CHARGING: "setpoint_charging",
        SmaEvChargerParameters.CHARGE_STOP: "charge_stop",
    },
)

select = SmaEvChargerSelect(
    hass,
    config_entry,
    device_info,
    description
)
```

--------------------------------

### Instantiate SmaEvChargerSwitch

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/switch-platform.md

Example of how to create an instance of the SmaEvChargerSwitch class. This involves defining the entity description with specific parameters and then initializing the switch with Home Assistant instance, config entry, device info, and the description.

```python
from custom_components.smaev.switch import SmaEvChargerSwitch, SmaEvChargerSwitchEntityDescription
from pysmaev.const import SmaEvChargerParameters

description = SmaEvChargerSwitchEntityDescription(
    key="manual_charging_release",
    translation_key="manual_charging_release",
    type="parameter",
    channel="Parameter.Chrg.ChrgApv",
    value_mapping={
        SmaEvChargerParameters.CHARGING_LOCK: False,
        SmaEvChargerParameters.CHARGING_RELEASE: True,
    },
)

switch = SmaEvChargerSwitch(
    hass,
    config_entry,
    device_info,
    description
)
```

--------------------------------

### Example Channels Dictionary Structure

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/data-structures.md

Illustrates the expected structure of the 'channels' dictionary within SmaEvChargerRuntimeData, categorizing available measurement and parameter channels.

```python
channels = {
    "measurement": [
        "Measurement.ChaSess.WhIn",
        "Measurement.Chrg.ModSw",
        "Measurement.GridMs.A.phsA",
        "Measurement.GridMs.A.phsB",
        "Measurement.GridMs.A.phsC",
        # ... more measurement channels
    ],
    "parameter": [
        "Parameter.Chrg.ChrgApv",
        "Parameter.Chrg.StpWhenFl",
        "Parameter.Chrg.StpWhenFlTm",
        # ... more parameter channels
    ]
}
```

--------------------------------

### Reconfigure Form Prepopulation

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/config-flow.md

Shows the reconfiguration form with suggested values pre-populated from the existing configuration. Uses the same schema as the user setup step.

```python
self.async_show_form(
    step_id="reconfigure",
    data_schema=self.add_suggested_values_to_schema(
        STEP_USER_DATA_SCHEMA,
        self._reconfigure_data  # Current values
    ),
    errors=errors,
)
```

--------------------------------

### Async Setup Entry for DateTime Entities

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/datetime-platform.md

Registers all datetime entities for the SMA EV Charger integration. This function takes the Home Assistant instance, configuration entry, and an entity adding callback as parameters.

```python
async def async_setup_entry(
    hass: HomeAssistant,
    config_entry: SmaEvChargerConfigEntry,
    async_add_entities: AddEntitiesCallback,
) -> None
```

--------------------------------

### Scan Interval Configuration Example

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/configuration.md

Shows how to set the `scan_interval` option to control the polling frequency of the device data. The default is 5 seconds.

```python
entry.options = {
    CONF_SCAN_INTERVAL: 10  # Poll every 10 seconds
}
```

--------------------------------

### Coordinator Update Handling Example

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/select-platform.md

Illustrates how the entity dynamically updates its available options based on device capabilities received during coordinator updates. It maps device values to human-readable options and updates the UI if options change.

```python
# Device returns [BOOST, OPTIMIZED, SETPOINT] as possible values
# Entity options become ["boost_charging", "optimized_charging", "setpoint_charging"]
# User sees only valid options in dropdown
```

--------------------------------

### Example Usage of validate_input

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/config-flow.md

Demonstrates how to use the validate_input function with sample data and how to handle the returned errors. This is useful for testing the validation logic.

```python
data = {
    "host": "192.168.1.100",
    "username": "installer",
    "password": "password",
    "ssl": True,
    "verify_ssl": False
}

errors = await validate_input(hass, data)

if not errors:
    # Input is valid
    pass
else:
    # Display errors to user
    # e.g., errors["base"] == "invalid_auth"
    pass
```

--------------------------------

### Authentication Warning Example

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/configuration.md

Demonstrates a typical warning message when a standard user account lacks access to certain channels, such as parameters or diagnostics.

```text
WARNING: Channel 'Parameter.Chrg.ChrgApv' is not accessible. Elevated rights might be required.
```

--------------------------------

### Multi-Device Support Example

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/overview.md

Illustrates how to support multiple EV chargers, where each charger requires a separate configuration entry. It shows distinct IP addresses and serial numbers for two devices and the corresponding entity naming convention.

```text
Device 1: 192.168.1.100 (Serial ABC123)
Device 2: 192.168.1.101 (Serial DEF456)

Entities:
- sensor.smaev_charger_abc123_charging_session_energy
- sensor.smaev_charger_def456_charging_session_energy
```

--------------------------------

### Config Flow Validation Error Handling

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/configuration.md

Provides an example of how the integration handles potential connection and authentication errors during the configuration validation process.

```python
errors: dict[str, str] = {}
try:
    await evcharger.open()
except pysmaev.exceptions.SmaEvChargerConnectionError:
    errors[CONF_BASE] = "cannot_connect"
except pysmaev.exceptions.SmaEvChargerAuthenticationError:
    errors[CONF_BASE] = "invalid_auth"
```

--------------------------------

### Async Setup Entry Function for SMA EV Charger Select Entities

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/select-platform.md

This function registers all select entities for the SMA EV Charger integration. It extracts device information, iterates through predefined descriptions, checks channel accessibility, creates select instances, and logs warnings for unavailable channels.

```python
async def async_setup_entry(
    hass: HomeAssistant,
    config_entry: SmaEvChargerConfigEntry,
    async_add_entities: AddEntitiesCallback,
) -> None:
    pass
```

--------------------------------

### Coordinator Update Handling Example

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/number-platform.md

Illustrates how the number entity automatically updates its range in Home Assistant when the device returns different min/max bounds than expected. The user will see the new bounds reflected in the UI.

```python
# Device returns different min/max bounds than expected
# Number entity automatically updates its range in Home Assistant
# User sees new bounds reflected in UI
```

--------------------------------

### Access Domain Data

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/constants.md

Example of how to access domain-specific data stored in `hass.data`. Shows retrieving the entire domain data dictionary and a specific entry's coordinator.

```python
from custom_components.smaev.const import (
    DOMAIN,
    SMAEV_COORDINATOR,
    SMAEV_MEASUREMENT,
)

# Get all data for domain
domain_data = hass.data[DOMAIN]  # dict[str, dict]

# Get specific entry's coordinator
entry_id = "abc123"
coordinator = hass.data[DOMAIN][entry_id][SMAEV_COORDINATOR]

# Get measurement data from coordinator
measurements = coordinator.data[SMAEV_MEASUREMENT]
```

--------------------------------

### Configure Polling Interval

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/README.md

Set the polling interval for the integration. This example shows how to modify the scan interval option, which will be enhanced with a UI in the future.

```python
entry.options[CONF_SCAN_INTERVAL] = 10  # Poll every 10 seconds
```

--------------------------------

### Handle Generic pysmaev Exception in Coordinator

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/errors.md

This example demonstrates catching any pysmaev base exception during device communication within the Home Assistant coordinator and re-raising it as an UpdateFailed exception. This ensures that general communication issues are handled gracefully.

```python
try:
    await self.evcharger.open()
except SmaEvChargerException as exc:
    raise UpdateFailed("Connection to device lost.") from exc
```

--------------------------------

### YAML: Automation Example for Charger Restart

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/services-and-actions.md

This YAML configuration shows a Home Assistant automation that uses the 'restart' device action for the SMA EV Charger. It's triggered at a specific time each day.

```yaml
automation:
  - alias: Daily Charger Restart
    trigger:
      platform: time
      at: "03:00:00"
    action:
      - type: restart
        device_id: abc1234567890def
        domain: smaev
```

--------------------------------

### Instantiate SmaEvChargerDateTime Entity

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/datetime-platform.md

Example of creating an instance of SmaEvChargerDateTime. It requires defining a SmaEvChargerDateTimeEntityDescription with key, translation key, type, and channel, then passing it along with other necessary parameters to the constructor.

```python
from custom_components.smaev.datetime import SmaEvChargerDateTime, SmaEvChargerDateTimeEntityDescription

description = SmaEvChargerDateTimeEntityDescription(
    key="end_charging_process",
    translation_key="end_charging_process",
    type="parameter",
    channel="Parameter.Chrg.Plan.StopTm",
)

datetime_entity = SmaEvChargerDateTime(
    hass,
    config_entry,
    device_info,
    description
)
```

--------------------------------

### Restart SMA EV Charger Device (Python API)

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/services-and-actions.md

Example of how to call the 'smaev.restart' service programmatically using the Home Assistant Python API. Ensure the 'hass' object is available.

```python
hass = get_current_hass()
await hass.services.async_call(
    "smaev",
    "restart",
    {"device_id": "abc1234567890def"}
)
```

--------------------------------

### Handle ConfigEntryNotReady with pysmaev Connection Error

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/errors.md

This code catches a pysmaev connection error during device setup and raises it as a Home Assistant ConfigEntryNotReady exception. This is used when the integration cannot establish a connection to the device.

```python
try:
    await evcharger.open()
except pysmaev.exceptions.SmaEvChargerConnectionError as exc:
    raise ConfigEntryNotReady from exc
```

--------------------------------

### Restart SMA EV Charger Device (YAML)

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/services-and-actions.md

Example of how to invoke the 'smaev.restart' service using YAML in automations or scripts. Requires the device_id of the charger.

```yaml
service: smaev.restart
data:
  device_id: abc1234567890def
```

--------------------------------

### Access Channel Data

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/constants.md

Example of how to retrieve specific data points (value, min, max) from a channel using helper functions. Assumes the channel data is available via a coordinator.

```python
from custom_components.smaev.const import (
    SMAEV_VALUE,
    SMAEV_MIN_VALUE,
    SMAEV_MAX_VALUE,
)
from pysmaev.helpers import get_parameters_channel

channel = get_parameters_channel(
    coordinator.data[SMAEV_PARAMETER],
    "Parameter.Chrg.Plan.En"
)

value = channel[SMAEV_VALUE]  # Current value
min_val = channel.get(SMAEV_MIN_VALUE)
max_val = channel.get(SMAEV_MAX_VALUE)
```

--------------------------------

### Get Available Device Actions

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/services-and-actions.md

Retrieves a list of available actions for a specific SMA EV Charger device. This is used to discover what actions can be automated.

```python
from custom_components.smaev.device_action import async_get_actions

device_id = "charger_123"
actions = await async_get_actions(hass, device_id)
# Returns:
# [
#   {
#     "device_id": "charger_123",
#     "domain": "smaev",
#     "type": "restart"
#   }
# ]
```

--------------------------------

### Configuration Schema for Reconfiguration

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/configuration.md

Defines the schema used for reconfiguring the integration, including host, credentials, and SSL settings. This schema is identical to the one used during initial setup.

```python
STEP_USER_DATA_SCHEMA = vol.Schema({
    vol.Required(CONF_HOST): str,
    vol.Required(CONF_USERNAME): str,
    vol.Required(CONF_PASSWORD): str,
    vol.Optional(CONF_SSL, default=True): cv.boolean,
    vol.Optional(CONF_VERIFY_SSL, default=False): cv.boolean,
})
```

--------------------------------

### Handle ConfigEntryAuthFailed with pysmaev Authentication Error

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/errors.md

This snippet demonstrates how to catch a pysmaev authentication error during device opening and re-raise it as a Home Assistant ConfigEntryAuthFailed exception. Use this when invalid credentials prevent integration setup.

```python
try:
    await evcharger.open()
except pysmaev.exceptions.SmaEvChargerAuthenticationError as exc:
    raise ConfigEntryAuthFailed from exc
```

--------------------------------

### SmaEvChargerNumber async_set_native_value Example

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/number-platform.md

Example of calling async_set_native_value to set the number entity to 30.0, which triggers a device update and coordinator refresh.

```python
# User sets number entity to 30
await number.async_set_native_value(30.0)
# Device receives "30", coordinator refreshes
```

--------------------------------

### async_setup_services

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/services-and-actions.md

Registers all integration services for controlling SMA EV Charger devices. This function makes the `smaev.restart` service available.

```APIDOC
## async_setup_services()

### Description
Registers all integration services for controlling SMA EV Charger devices. This function makes the `smaev.restart` service available.

### Method
`async_setup_services(hass: HomeAssistant) -> None`

### Parameters
#### Path Parameters
- **hass** (HomeAssistant) - Required - Home Assistant instance

### Behavior
1. Registers the `smaev.restart` service
2. Binds service handler to call internal `_async_service_reset()`
3. Applies SERVICE_RESTART_SCHEMA validation

### Example
```python
from homeassistant.core import HomeAssistant
from custom_components.smaev.services import async_setup_services

hass = get_current_hass()
async_setup_services(hass)
# Services are now available
```
```

--------------------------------

### async_setup_entry

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/datetime-platform.md

Registers all datetime entities for the SMA EV Charger.

```APIDOC
## Setup Function: async_setup_entry()

### Description
Registers all datetime entities for the SMA EV Charger.

### Method
```python
async def async_setup_entry(
    hass: HomeAssistant,
    config_entry: SmaEvChargerConfigEntry,
    async_add_entities: AddEntitiesCallback,
) -> None
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| hass | HomeAssistant | ✓ | — | Home Assistant instance |
| config_entry | SmaEvChargerConfigEntry | ✓ | — | Integration config entry |
| async_add_entities | AddEntitiesCallback | ✓ | — | Callback to register entities |
```

--------------------------------

### Turn On SmaEvChargerSwitch

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/switch-platform.md

Demonstrates how to turn on a switch entity. This action sends the corresponding parameter value to the device, updates the local state, and triggers a coordinator refresh to synchronize with the device.

```python
# Switch entity is on in Home Assistant
await switch.async_turn_on()
# Device receives parameter change, state syncs back
```

--------------------------------

### Accessing SmaEvChargerRuntimeData and its components

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/data-structures.md

Demonstrates how to access the runtime data from a configuration entry and interact with the device client and data coordinator. Shows how to check for the availability of specific channels.

```python
config_entry: SmaEvChargerConfigEntry
runtime_data = config_entry.runtime_data

# Access device client
evcharger = runtime_data.evcharger
await evcharger.set_parameter(value, channel)

# Access coordinator
coordinator = runtime_data.coordinator
current_measurements = coordinator.data["measurement"]

# Check available channels
if "Measurement.ChaSess.WhIn" in runtime_data.channels["measurement"]:
    # Channel is available
    pass
```

--------------------------------

### async_turn_on

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/switch-platform.md

Turns the switch on by sending the appropriate parameter value to the device. It updates the local state and triggers a coordinator refresh.

```APIDOC
## async_turn_on()

### Description
Turns the switch on by sending the appropriate parameter value to the device. It updates the local state and triggers a coordinator refresh.

### Method
```python
async def async_turn_on(self, **kwargs: Any) -> None
```

### Parameters
#### Parameters
- **kwargs** (dict) - Unused additional parameters

### Behavior
1. Retrieves evcharger from coordinator
2. Converts boolean True to mapped parameter value using inverted value_mapping
3. Sends parameter to device via `evcharger.set_parameter()`
4. Updates local state to True
5. Triggers coordinator refresh to sync with device

### Example
```python
# Switch entity is on in Home Assistant
await switch.async_turn_on()
# Device receives parameter change, state syncs back
```

### Source
`custom_components/smaev/switch.py:140-148`
```

--------------------------------

### Initialize and Use SmaEvCharger API Client

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/overview.md

Establishes a connection to the EV charger using the pysmaev library. It shows how to open the connection, retrieve device information, list measurement and parameter channels, fetch data, update parameters, and close the connection.

```python
evcharger = pysmaev.core.SmaEvCharger(
    session,      # aiohttp ClientSession
    url,          # Device URL (http/https)
    username,     # Credentials
    password
)

await evcharger.open()                           # Establish connection
await evcharger.device_info()                    # Get device details
await evcharger.get_measurement_channels()       # List measurements
await evcharger.get_parameter_channels()         # List parameters
await evcharger.request_measurements()           # Fetch current measurements
await evcharger.request_parameters()             # Fetch current parameters
await evcharger.set_parameter(value, channel)    # Update parameter
await evcharger.close()                          # Close connection
```

--------------------------------

### Accessing Coordinator Data

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/data-structures.md

Demonstrates how to access measurement and parameter data from the coordinator and use helper functions from pysmaev.

```python
# From coordinator.data
measurements = coordinator.data["measurement"]
parameters = coordinator.data["parameter"]

# Helper functions from pysmaev
from pysmaev.helpers import get_measurements_channel, get_parameters_channel

channel_data = get_measurements_channel(measurements, "Measurement.ChaSess.WhIn")
value = channel_data[0]["value"]  # Measurements are lists

param_data = get_parameters_channel(parameters, "Parameter.Chrg.ChrgApv")
value = param_data["value"]  # Parameters are dicts
```

--------------------------------

### Charging Station Meter Reading Sensor Configuration

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/sensor-platform.md

Configures a sensor to track the total energy consumed by the charging station since installation, measured in watt-hours.

```python
key="charging_station_meter_reading"
channel="Measurement.Metering.GridMs.TotWhIn.ChaSta"
device_class=SensorDeviceClass.ENERGY
state_class=SensorStateClass.TOTAL_INCREASING
unit=UnitOfEnergy.WATT_HOUR
```

--------------------------------

### __init__()

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/coordinator.md

Initializes the SmaEvChargerCoordinator with a Home Assistant instance, configuration entry, and an SmaEvCharger device instance. It configures the polling interval based on entry options or a default value.

```APIDOC
## __init__()

### Description
Initializes the data update coordinator with configurable polling interval.

### Parameters
#### Path Parameters
- **hass** (HomeAssistant) - Required - Home Assistant instance
- **entry** (ConfigEntry) - Required - Configuration entry containing scan interval
- **evcharger** (SmaEvCharger) - Required - pysmaev SmaEvCharger instance for device communication

### Behavior
1. Extracts scan interval from entry.options with fallback to DEFAULT_SCAN_INTERVAL (5 seconds)
2. Calls parent class constructor with configured update interval
3. Stores reference to evcharger instance
4. Initializes coordinator name as "smaev"

### Example
```python
from custom_components.smaev.coordinator import SmaEvChargerCoordinator
import pysmaev.core

hass = get_current_hass()
entry = hass.config_entries.async_get_entry("entry_id")
e charger = pysmaev.core.SmaEvCharger(session, url, username, password)

coordinator = SmaEvChargerCoordinator(hass, entry, evcharger)
```

### Source
`custom_components/smaev/coordinator.py:31-39`
```

--------------------------------

### async_call_action_from_config

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/services-and-actions.md

Executes a device action based on a provided configuration, currently supporting the 'restart' action type.

```APIDOC
## async_call_action_from_config()

### Description
Executes a device action based on a provided configuration, currently supporting the 'restart' action type.

### Method
`async def async_call_action_from_config(
    hass: HomeAssistant,
    config: ConfigType,
    variables: TemplateVarsType,
    context: Context | None,
) -> None`

### Parameters
#### Path Parameters
- **hass** (HomeAssistant) - Required - Home Assistant instance
- **config** (ConfigType) - Required - Action configuration dict
- **variables** (TemplateVarsType) - Required - Template variables (unused)
- **context** (Context | None) - Optional - Automation context

### Config Format
```python
{
    "device_id": "charger_device_id",
    "domain": "smaev",
    "type": "restart"  # Only action type currently supported
}
```
```

--------------------------------

### Restart SMA EV Charger Device (Lovelace)

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/services-and-actions.md

Example of calling the 'smaev.restart' service from a Lovelace UI service call card. This is useful for creating manual control buttons.

```yaml
type: service
service: smaev.restart
data:
  device_id: abc1234567890def
```

--------------------------------

### Default Scan Interval

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/constants.md

Sets the default polling interval in seconds for coordinator updates. This is used as a fallback when `entry.options[CONF_SCAN_INTERVAL]` is not set, typically during initial setup. Recommended range is 3-60 seconds.

```python
DEFAULT_SCAN_INTERVAL = 5
```

--------------------------------

### Initialize SMA EV Charger Integration

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/setup-functions.md

The core entry point for setting up the SMA EV Charger integration. It initializes configuration and entities, handling potential connection and authentication errors.

```python
async def async_setup_entry(
    hass: HomeAssistant, 
    entry: SmaEvChargerConfigEntry
) -> bool:
    ...

# Within Home Assistant config flow or automated setup
hass = get_current_hass()
entry = ConfigEntry(
    domain="smaev",
    data={
        "host": "192.168.1.100",
        "username": "installer",
        "password": "password",
        "ssl": True,
        "verify_ssl": False
    },
    ...
)
success = await async_setup_entry(hass, entry)
if success:
    # Integration loaded successfully
    # All entities now available
    pass

```

--------------------------------

### Home Assistant Sensor Platform Imports

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/types.md

Import sensor-specific classes for creating sensor entities, including SensorEntity, SensorEntityDescription, SensorDeviceClass, and SensorStateClass.

```python
from homeassistant.components.sensor import (
    SensorEntity,
    SensorEntityDescription,
    SensorDeviceClass,
    SensorStateClass,
)
# Similar imports for switch, number, select, datetime
```

--------------------------------

### Initialize SmaEvChargerSensor

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/sensor-platform.md

Constructor for the SmaEvChargerSensor class. It requires Home Assistant instance, config entry, device info, and entity description.

```python
def __init__(
    self,
    hass: HomeAssistant,
    config_entry: SmaEvChargerConfigEntry,
    device_info: DeviceInfo,
    entity_description: SmaEvChargerSensorEntityDescription,
) -> None:
```

--------------------------------

### Python: Call Device Action from Config

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/services-and-actions.md

This Python snippet demonstrates how to programmatically call a device action from a configuration dictionary. It's used internally by Home Assistant to execute actions defined in automations.

```python
# From automation triggers
config = {
    "device_id": "charger_123",
    "domain": "smaev",
    "type": "restart"
}

await async_call_action_from_config(
    hass,
    config,
    {},
    None
)
# Triggers smaev.restart service
```

--------------------------------

### Configuration Keys Constants

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/config-flow.md

Imports common configuration keys used in Home Assistant integrations. These constants help maintain consistency and avoid typos.

```python
from homeassistant.const import (
    CONF_HOST,
    CONF_PASSWORD,
    CONF_SSL,
    CONF_USERNAME,
    CONF_VERIFY_SSL,
    CONF_BASE,
)
```

--------------------------------

### DeviceInfo Creation for SMA EV Charger

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/data-structures.md

Shows how to construct a DeviceInfo object for the Home Assistant device registry. It includes essential details like configuration URL, unique identifiers, manufacturer, model, and software/hardware versions.

```python
from homeassistant.helpers.device_registry import DeviceInfo
from custom_components.smaev.const import DOMAIN

# Assuming smaev_device_info is a dictionary containing device details
smaev_device_info = {
    "serial": "123456789",
    "manufacturer": "SMA",
    "model": "EV Charger",
    "name": "My EV Charger",
    "sw_version": "1.2.3"
}
url = "http://192.168.1.100"

device_info = DeviceInfo(
    configuration_url=url,
    identifiers={(DOMAIN, smaev_device_info["serial"])},
    manufacturer=smaev_device_info["manufacturer"],
    model=smaev_device_info["model"],
    name=smaev_device_info["name"],
    hw_version=smaev_device_info["serial"],
    sw_version=smaev_device_info["sw_version"],
)
```

--------------------------------

### Accessing Integration Data

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/configuration.md

Shows how to retrieve integration-specific data using the `DOMAIN` constant, typically within Home Assistant.

```python
from custom_components.smaev.const import DOMAIN, DEFAULT_SCAN_INTERVAL

domain_data = hass.data[DOMAIN]  # Access integration data
```

--------------------------------

### Async Step Reconfigure Function Signature

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/config-flow.md

Handles the reconfiguration of an existing device, allowing users to update connection details. It takes updated user input and returns a configuration flow result.

```python
async def async_step_reconfigure(
    self, 
    user_input: dict[str, Any] | None = None
) -> ConfigFlowResult
```

--------------------------------

### Extend Sensor Descriptions with Custom Descriptions

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/overview.md

Demonstrates how to extend the existing sensor descriptions by defining a new tuple of SmaEvChargerSensorEntityDescription objects. This allows for the addition of new sensors to the integration.

```python
from custom_components.smaev.sensor import SENSOR_DESCRIPTIONS

# Add new sensor descriptions
CUSTOM_DESCRIPTIONS = (
    SmaEvChargerSensorEntityDescription(...),
)
```

--------------------------------

### Home Assistant Core Imports

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/types.md

Import core classes for Home Assistant development, including HomeAssistant, ConfigEntry, DeviceInfo, EntityDescription, and DataUpdateCoordinator.

```python
from homeassistant.core import HomeAssistant
from homeassistant.config_entries import ConfigEntry
from homeassistant.helpers.device_registry import DeviceInfo
from homeassistant.helpers.entity import EntityDescription
from homeassistant.helpers.update_coordinator import DataUpdateCoordinator
```

--------------------------------

### Configuration Parameters

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/README.md

Lists the parameters required for configuring the SMA EV Charger integration.

```APIDOC
## Configuration Parameters

### `host`

- **Type**: string
- **Required**: ✓
- **Description**: Device IP address.

### `username`

- **Type**: string
- **Required**: ✓
- **Description**: Device username.

### `password`

- **Type**: string
- **Required**: ✓
- **Description**: Device password.

### `ssl`

- **Type**: boolean
- **Default**: true
- **Required**: —
- **Description**: Use HTTPS for connection.

### `verify_ssl`

- **Type**: boolean
- **Default**: false
- **Required**: —
- **Description**: Verify SSL certificate.

### `scan_interval`

- **Type**: integer
- **Default**: 5
- **Required**: —
- **Description**: Polling interval in seconds.
```

--------------------------------

### File Structure of SMA EV Charger Integration

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/README.md

Overview of the directory and file structure for the custom_components/smaev integration.

```text
custom_components/smaev/
├── __init__.py                  # Setup and unload
├── const.py                     # Constants
├── config_flow.py               # User configuration
├── coordinator.py               # Data coordination
├── sensor.py                    # Sensor entities
├── switch.py                    # Switch entities
├── number.py                    # Number entities
├── select.py                    # Select entities
├── datetime.py                  # DateTime entities
├── services.py                  # Service handlers
├── device_action.py             # Device actions
├── manifest.json                # Integration metadata
├── strings.json                 # UI strings (English)
└── translations/
    ├── en.json                  # English translations
    └── de.json                  # German translations
```

--------------------------------

### Energy Charge Session Configuration

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/number-platform.md

Configures the target energy for the next charging session in kWh. Supports precise control with a step of 0.1 kWh.

```python
key="energy_charge_session"
channel="Parameter.Chrg.Plan.En"
native_step=0.1
mode=NumberMode.BOX
unit=UnitOfEnergy.KILO_WATT_HOUR
enabled_by_default=True
```

--------------------------------

### Create a Custom Entity Inheriting from CoordinatorEntity

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/overview.md

Provides a template for creating custom entities within the integration. It shows how to inherit from CoordinatorEntity and implement the _handle_coordinator_update method to access coordinator data and interact with the EV charger.

```python
from custom_components.smaev.coordinator import SmaEvChargerCoordinator

class CustomEntity(CoordinatorEntity):
    def __init__(self, coordinator: SmaEvChargerCoordinator):
        super().__init__(coordinator)
    
    @callback
    def _handle_coordinator_update(self) -> None:
        # Access: self.coordinator.data["measurement"]
        # Access: self.coordinator.evcharger.set_parameter(...)
```

--------------------------------

### Initialize Logger

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/errors.md

Standard Python practice for creating a module-specific logger instance. Used for all logging within the module.

```python
_LOGGER = logging.getLogger(__name__)
```

--------------------------------

### async_get_actions

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/services-and-actions.md

Retrieves a list of available device-level actions for a given SMA EV Charger device.

```APIDOC
## async_get_actions()

### Description
Retrieves a list of available device-level actions for a given SMA EV Charger device.

### Method
`async def async_get_actions(hass: HomeAssistant, device_id: str) -> list[dict[str, str]]`

### Parameters
#### Path Parameters
- **hass** (HomeAssistant) - Required - Home Assistant instance
- **device_id** (str) - Required - Device registry ID

### Returns
`list[dict[str, str]]` — List of available action configurations for the device

### Behavior
1. Looks up device in device registry
2. Returns empty list if device not found
3. Builds base action dict with device_id and domain
4. Appends "restart" action type
5. Returns list with restart action

### Example
```python
from custom_components.smaev.device_action import async_get_actions

device_id = "charger_123"
actions = await async_get_actions(hass, device_id)
# Returns:
# [
#   {
#     "device_id": "charger_123",
#     "domain": "smaev",
#     "type": "restart"
#   }
# ]
```
```

--------------------------------

### Call Device Action from Configuration

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/services-and-actions.md

Executes a device action based on a configuration dictionary. Currently, only the 'restart' action type is supported for the SMA EV Charger.

```python
{
    "device_id": "charger_device_id",
    "domain": "smaev",
    "type": "restart"  # Only action type currently supported
}
```

--------------------------------

### Configuration and Control

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/README.md

Covers the configuration flow, services, and constants used by the integration.

```APIDOC
## Configuration and Control

### Config Flow

#### Description
Manages the user interface for configuring and reconfiguring the SMA EV Charger integration.

- `SmaEvChargerConfigFlow` class
- `validate_input()` validation
- User and Reconfigure steps

### Services and Actions

#### Description
Handles the registration and cleanup of services and device actions.

- `async_setup_services()` - Service registration
- `async_unload_services()` - Service cleanup
- `smaev.restart` service
- Device actions

### Constants

#### Description
Defines all constant values and keys used throughout the integration.

- Domain identifiers
- Data type identifiers
- Channel data keys
- Default values

### Data Structures

#### Description
Defines the data classes and type aliases used for runtime data and configuration.

- `SmaEvChargerRuntimeData` dataclass
- `SmaEvChargerConfigEntry` type alias
- Entity description classes
- DeviceInfo structure
```

--------------------------------

### SmaEvChargerCoordinator Usage

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/overview.md

Demonstrates the initialization of the SmaEvChargerCoordinator, which manages device polling and entity updates. It shows the structure of the coordinator's data attribute and explains how updates are triggered and handled by subscribed entities.

```python
coordinator = SmaEvChargerCoordinator(hass, entry, evcharger)

# Data structure:
coordinator.data = {
    "measurement": [...],  # Current measurement values
    "parameter": [...]     # Current parameter values
}

# Updates triggered by:
# - Periodic timer (every 5 seconds)
# - Manual refresh requests from entities
# - Service calls

# Entities subscribe to coordinator:
# - Inherit from CoordinatorEntity
# - Implement _handle_coordinator_update()
# - Called when new data arrives
```

--------------------------------

### Home Assistant Standard Constants

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/constants.md

Commonly used constants from `homeassistant.const` for configuration and device identification.

```python
CONF_HOST = "host"              # Device IP address
CONF_USERNAME = "username"      # Authentication user
CONF_PASSWORD = "password"      # Authentication password
CONF_SSL = "ssl"                # Use HTTPS flag
CONF_VERIFY_SSL = "verify_ssl"  # Verify SSL certificate
CONF_SCAN_INTERVAL = "scan_interval"  # Polling interval seconds
CONF_DEVICE_ID = "device_id"    # Device registry ID
```

--------------------------------

### Runtime Data Key for Low-Level Client

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/constants.md

Key for the low-level device client object, pysmaev.core.SmaEvCharger. This is stored in runtime data but not typically accessed directly.

```python
SMAEV_OBJECT = "pysmaev"
```

--------------------------------

### Coordinator Update Handling

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/datetime-platform.md

Converts device timestamp values to datetime objects.

```APIDOC
## Coordinator Update Handling

### Description
Converts device timestamp values to datetime objects.

### Behavior

1. Retrieves channel data from coordinator
2. Extracts value from channel (Unix timestamp as integer string)
3. Converts timestamp to datetime in UTC timezone using `datetime.fromtimestamp()`
4. Updates _attr_native_value with the datetime object

### Example

```python
# Device returns timestamp "1750636800" (timestamp format)
# Entity converts to datetime(2025, 6, 15, 14:30, tzinfo=UTC)
# User sees formatted datetime in Home Assistant UI
```
```

--------------------------------

### SmaEvChargerCoordinator Constructor

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/coordinator.md

Initializes the SmaEvChargerCoordinator with Home Assistant instance, configuration entry, and SmaEvCharger instance. It configures the polling interval based on entry options.

```python
def __init__(
    self, 
    hass: HomeAssistant, 
    entry: ConfigEntry, 
    evcharger: SmaEvCharger
) -> None
```

--------------------------------

### Integration Constants

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/configuration.md

Lists essential constants used within the SMA EV Charger integration, such as the domain name and default scan interval.

```python
DOMAIN = "smaev"
DEFAULT_SCAN_INTERVAL = 5
SMAEV_MEASUREMENT = "measurement"
SMAEV_PARAMETER = "parameter"
SMAEV_COORDINATOR = "coordinator"
SMAEV_DEVICE_INFO = "device_info"
SMAEV_CHANNELS = "channels"
```

--------------------------------

### async_get_coordinator_by_device_id Utility Function

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/coordinator.md

Retrieves the SmaEvChargerCoordinator for a given device ID. It looks up the device in the Home Assistant device registry and finds the associated coordinator.

```python
@callback
def async_get_coordinator_by_device_id(
    hass: HomeAssistant, 
    device_id: str
) -> SmaEvChargerCoordinator
```

--------------------------------

### Setting Device Configuration URL

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/configuration.md

Assigns the constructed URL to the configuration_url field of the DeviceInfo object. This allows users to directly access the device's web UI from Home Assistant.

```python
device_info = DeviceInfo(
    configuration_url=url,
    # ... other fields
)
```

--------------------------------

### Coordinator Update Handling for Timestamps

Source: https://github.com/alengwenus/ha-sma-ev-charger/blob/main/_autodocs/api-reference/datetime-platform.md

Handles updates from the coordinator by converting device timestamp values (received as integer strings) into timezone-aware datetime objects. The converted datetime is then updated as the entity's native value, displayed in the Home Assistant UI.

```python
# Device returns timestamp "1750636800" (timestamp format)
# Entity converts to datetime(2025, 6, 15, 14:30, tzinfo=UTC)
# User sees formatted datetime in Home Assistant UI
```