Homevolt 0.1.0__tar.gz

homevolt-0.1.0/Homevolt.egg-info/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: Homevolt
+Version: 0.1.0
+Summary: Python library for Homevolt EMS devices
+Author-email: Your Name <your.email@example.com>
+License: GPL-3.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.8.0
+
+# pyHomevolt
+
+Python library for Homevolt EMS devices.
+
+Get real-time data from your Homevolt Energy Management System, including:
+- Voltage, current, and power measurements
+- Battery state of charge and temperature
+- Grid, solar, and load sensor data
+- Schedule information
+
+## Install
+
+```bash
+pip install pyHomevolt
+```
+
+## Example
+
+```python
+import asyncio
+import aiohttp
+import homevolt
+
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        homevolt_connection = homevolt.Homevolt(
+            ip_address="192.168.1.100",
+            password="optional_password",
+            websession=session,
+        )
+        await homevolt_connection.update_info()
+        
+        device = homevolt_connection.get_device()
+        print(f"Device ID: {device.device_id}")
+        print(f"Current Power: {device.sensors['Power'].value} W")
+        print(f"Battery SOC: {device.sensors['Battery State of Charge'].value * 100}%")
+        
+        # Access all sensors
+        for sensor_name, sensor in device.sensors.items():
+            print(f"{sensor_name}: {sensor.value} ({sensor.type.value})")
+        
+        # Access device metadata
+        for device_id, metadata in device.device_metadata.items():
+            print(f"{device_id}: {metadata.name} ({metadata.model})")
+        
+        await homevolt_connection.close_connection()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Example with context manager
+
+```python
+import asyncio
+import aiohttp
+import homevolt
+
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        async with homevolt.Homevolt(
+            ip_address="192.168.1.100",
+            password="optional_password",
+            websession=session,
+        ) as homevolt_connection:
+            await homevolt_connection.update_info()
+            
+            device = homevolt_connection.get_device()
+            await device.update_info()  # Refresh data
+            
+            print(f"Device ID: {device.device_id}")
+            print(f"Available sensors: {list(device.sensors.keys())}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## API Reference
+
+### Homevolt
+
+Main class for connecting to a Homevolt device.
+
+#### `Homevolt(ip_address, password=None, websession=None)`
+
+Initialize a Homevolt connection.
+
+- `ip_address` (str): IP address of the Homevolt device
+- `password` (str, optional): Password for authentication
+- `websession` (aiohttp.ClientSession, optional): HTTP session. If not provided, one will be created.
+
+#### Methods
+
+- `async update_info()`: Fetch and update device information
+- `get_device()`: Get the Device object
+- `async close_connection()`: Close the connection and clean up resources
+
+### Device
+
+Represents a Homevolt EMS device.
+
+#### Properties
+
+- `device_id` (str): Device identifier
+- `sensors` (dict[str, Sensor]): Dictionary of sensor readings
+- `device_metadata` (dict[str, DeviceMetadata]): Dictionary of device metadata
+- `current_schedule` (dict): Current schedule information
+
+#### Methods
+
+- `async update_info()`: Fetch latest EMS and schedule data
+- `async fetch_ems_data()`: Fetch EMS data specifically
+- `async fetch_schedule_data()`: Fetch schedule data specifically
+
+### Data Models
+
+#### Sensor
+
+- `value` (float | str | None): Sensor value
+- `type` (SensorType): Type of sensor
+- `device_identifier` (str): Device identifier for grouping sensors
+
+#### DeviceMetadata
+
+- `name` (str): Device name
+- `model` (str): Device model
+
+#### SensorType
+
+Enumeration of sensor types:
+- `VOLTAGE`
+- `CURRENT`
+- `POWER`
+- `ENERGY_INCREASING`
+- `ENERGY_TOTAL`
+- `FREQUENCY`
+- `TEMPERATURE`
+- `PERCENTAGE`
+- `SIGNAL_STRENGTH`
+- `COUNT`
+- `TEXT`
+- `SCHEDULE_TYPE`
+
+### Exceptions
+
+- `HomevoltException`: Base exception for all Homevolt errors
+- `HomevoltConnectionError`: Connection or network errors
+- `HomevoltAuthenticationError`: Authentication failures
+- `HomevoltDataError`: Data parsing errors
+
+## License
+
+GPL-3.0
+

homevolt-0.1.0/Homevolt.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+Homevolt.egg-info/PKG-INFO
+Homevolt.egg-info/SOURCES.txt
+Homevolt.egg-info/dependency_links.txt
+Homevolt.egg-info/requires.txt
+Homevolt.egg-info/top_level.txt
+homevolt/__init__.py
+homevolt/const.py
+homevolt/device.py
+homevolt/exceptions.py
+homevolt/homevolt.py
+homevolt/models.py

homevolt-0.1.0/Homevolt.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

homevolt-0.1.0/Homevolt.egg-info/requires.txt

@@ -0,0 +1 @@
+aiohttp>=3.8.0

homevolt-0.1.0/Homevolt.egg-info/top_level.txt

@@ -0,0 +1 @@
+homevolt

homevolt-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: Homevolt
+Version: 0.1.0
+Summary: Python library for Homevolt EMS devices
+Author-email: Your Name <your.email@example.com>
+License: GPL-3.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.8.0
+
+# pyHomevolt
+
+Python library for Homevolt EMS devices.
+
+Get real-time data from your Homevolt Energy Management System, including:
+- Voltage, current, and power measurements
+- Battery state of charge and temperature
+- Grid, solar, and load sensor data
+- Schedule information
+
+## Install
+
+```bash
+pip install pyHomevolt
+```
+
+## Example
+
+```python
+import asyncio
+import aiohttp
+import homevolt
+
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        homevolt_connection = homevolt.Homevolt(
+            ip_address="192.168.1.100",
+            password="optional_password",
+            websession=session,
+        )
+        await homevolt_connection.update_info()
+        
+        device = homevolt_connection.get_device()
+        print(f"Device ID: {device.device_id}")
+        print(f"Current Power: {device.sensors['Power'].value} W")
+        print(f"Battery SOC: {device.sensors['Battery State of Charge'].value * 100}%")
+        
+        # Access all sensors
+        for sensor_name, sensor in device.sensors.items():
+            print(f"{sensor_name}: {sensor.value} ({sensor.type.value})")
+        
+        # Access device metadata
+        for device_id, metadata in device.device_metadata.items():
+            print(f"{device_id}: {metadata.name} ({metadata.model})")
+        
+        await homevolt_connection.close_connection()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Example with context manager
+
+```python
+import asyncio
+import aiohttp
+import homevolt
+
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        async with homevolt.Homevolt(
+            ip_address="192.168.1.100",
+            password="optional_password",
+            websession=session,
+        ) as homevolt_connection:
+            await homevolt_connection.update_info()
+            
+            device = homevolt_connection.get_device()
+            await device.update_info()  # Refresh data
+            
+            print(f"Device ID: {device.device_id}")
+            print(f"Available sensors: {list(device.sensors.keys())}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## API Reference
+
+### Homevolt
+
+Main class for connecting to a Homevolt device.
+
+#### `Homevolt(ip_address, password=None, websession=None)`
+
+Initialize a Homevolt connection.
+
+- `ip_address` (str): IP address of the Homevolt device
+- `password` (str, optional): Password for authentication
+- `websession` (aiohttp.ClientSession, optional): HTTP session. If not provided, one will be created.
+
+#### Methods
+
+- `async update_info()`: Fetch and update device information
+- `get_device()`: Get the Device object
+- `async close_connection()`: Close the connection and clean up resources
+
+### Device
+
+Represents a Homevolt EMS device.
+
+#### Properties
+
+- `device_id` (str): Device identifier
+- `sensors` (dict[str, Sensor]): Dictionary of sensor readings
+- `device_metadata` (dict[str, DeviceMetadata]): Dictionary of device metadata
+- `current_schedule` (dict): Current schedule information
+
+#### Methods
+
+- `async update_info()`: Fetch latest EMS and schedule data
+- `async fetch_ems_data()`: Fetch EMS data specifically
+- `async fetch_schedule_data()`: Fetch schedule data specifically
+
+### Data Models
+
+#### Sensor
+
+- `value` (float | str | None): Sensor value
+- `type` (SensorType): Type of sensor
+- `device_identifier` (str): Device identifier for grouping sensors
+
+#### DeviceMetadata
+
+- `name` (str): Device name
+- `model` (str): Device model
+
+#### SensorType
+
+Enumeration of sensor types:
+- `VOLTAGE`
+- `CURRENT`
+- `POWER`
+- `ENERGY_INCREASING`
+- `ENERGY_TOTAL`
+- `FREQUENCY`
+- `TEMPERATURE`
+- `PERCENTAGE`
+- `SIGNAL_STRENGTH`
+- `COUNT`
+- `TEXT`
+- `SCHEDULE_TYPE`
+
+### Exceptions
+
+- `HomevoltException`: Base exception for all Homevolt errors
+- `HomevoltConnectionError`: Connection or network errors
+- `HomevoltAuthenticationError`: Authentication failures
+- `HomevoltDataError`: Data parsing errors
+
+## License
+
+GPL-3.0
+

homevolt-0.1.0/README.md

@@ -0,0 +1,158 @@
+# pyHomevolt
+
+Python library for Homevolt EMS devices.
+
+Get real-time data from your Homevolt Energy Management System, including:
+- Voltage, current, and power measurements
+- Battery state of charge and temperature
+- Grid, solar, and load sensor data
+- Schedule information
+
+## Install
+
+```bash
+pip install pyHomevolt
+```
+
+## Example
+
+```python
+import asyncio
+import aiohttp
+import homevolt
+
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        homevolt_connection = homevolt.Homevolt(
+            ip_address="192.168.1.100",
+            password="optional_password",
+            websession=session,
+        )
+        await homevolt_connection.update_info()
+        
+        device = homevolt_connection.get_device()
+        print(f"Device ID: {device.device_id}")
+        print(f"Current Power: {device.sensors['Power'].value} W")
+        print(f"Battery SOC: {device.sensors['Battery State of Charge'].value * 100}%")
+        
+        # Access all sensors
+        for sensor_name, sensor in device.sensors.items():
+            print(f"{sensor_name}: {sensor.value} ({sensor.type.value})")
+        
+        # Access device metadata
+        for device_id, metadata in device.device_metadata.items():
+            print(f"{device_id}: {metadata.name} ({metadata.model})")
+        
+        await homevolt_connection.close_connection()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Example with context manager
+
+```python
+import asyncio
+import aiohttp
+import homevolt
+
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        async with homevolt.Homevolt(
+            ip_address="192.168.1.100",
+            password="optional_password",
+            websession=session,
+        ) as homevolt_connection:
+            await homevolt_connection.update_info()
+            
+            device = homevolt_connection.get_device()
+            await device.update_info()  # Refresh data
+            
+            print(f"Device ID: {device.device_id}")
+            print(f"Available sensors: {list(device.sensors.keys())}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## API Reference
+
+### Homevolt
+
+Main class for connecting to a Homevolt device.
+
+#### `Homevolt(ip_address, password=None, websession=None)`
+
+Initialize a Homevolt connection.
+
+- `ip_address` (str): IP address of the Homevolt device
+- `password` (str, optional): Password for authentication
+- `websession` (aiohttp.ClientSession, optional): HTTP session. If not provided, one will be created.
+
+#### Methods
+
+- `async update_info()`: Fetch and update device information
+- `get_device()`: Get the Device object
+- `async close_connection()`: Close the connection and clean up resources
+
+### Device
+
+Represents a Homevolt EMS device.
+
+#### Properties
+
+- `device_id` (str): Device identifier
+- `sensors` (dict[str, Sensor]): Dictionary of sensor readings
+- `device_metadata` (dict[str, DeviceMetadata]): Dictionary of device metadata
+- `current_schedule` (dict): Current schedule information
+
+#### Methods
+
+- `async update_info()`: Fetch latest EMS and schedule data
+- `async fetch_ems_data()`: Fetch EMS data specifically
+- `async fetch_schedule_data()`: Fetch schedule data specifically
+
+### Data Models
+
+#### Sensor
+
+- `value` (float | str | None): Sensor value
+- `type` (SensorType): Type of sensor
+- `device_identifier` (str): Device identifier for grouping sensors
+
+#### DeviceMetadata
+
+- `name` (str): Device name
+- `model` (str): Device model
+
+#### SensorType
+
+Enumeration of sensor types:
+- `VOLTAGE`
+- `CURRENT`
+- `POWER`
+- `ENERGY_INCREASING`
+- `ENERGY_TOTAL`
+- `FREQUENCY`
+- `TEMPERATURE`
+- `PERCENTAGE`
+- `SIGNAL_STRENGTH`
+- `COUNT`
+- `TEXT`
+- `SCHEDULE_TYPE`
+
+### Exceptions
+
+- `HomevoltException`: Base exception for all Homevolt errors
+- `HomevoltConnectionError`: Connection or network errors
+- `HomevoltAuthenticationError`: Authentication failures
+- `HomevoltDataError`: Data parsing errors
+
+## License
+
+GPL-3.0
+

homevolt-0.1.0/homevolt/__init__.py

@@ -0,0 +1,24 @@
+"""Python library for Homevolt EMS devices."""
+
+from .device import Device
+from .exceptions import (
+    HomevoltAuthenticationError,
+    HomevoltConnectionError,
+    HomevoltDataError,
+    HomevoltException,
+)
+from .homevolt import Homevolt
+from .models import DeviceMetadata, Sensor, SensorType
+
+__all__ = [
+    "Device",
+    "DeviceMetadata",
+    "Homevolt",
+    "HomevoltAuthenticationError",
+    "HomevoltConnectionError",
+    "HomevoltDataError",
+    "HomevoltException",
+    "Sensor",
+    "SensorType",
+]
+

homevolt-0.1.0/homevolt/const.py

@@ -0,0 +1,23 @@
+"""Constants for the Homevolt library."""
+
+# API endpoints
+ENDPOINT_EMS = "/ems.json"
+ENDPOINT_SCHEDULE = "/schedule.json"
+
+SCHEDULE_TYPE = {
+    0: "Idle",
+    1: "Charge Setpoint",
+    2: "Discharge Setpoint",
+    3: "Charge Grid Setpoint",
+    4: "Discharge Grid Setpoint",
+    5: "Charge/Discharge Grid Setpoint",
+}
+
+# Device type mappings for sensors
+DEVICE_MAP = {
+    "grid": "grid",
+    "solar": "solar",
+    "load": "load",
+    "house": "load",
+}
+

homevolt-0.1.0/homevolt/device.py

@@ -0,0 +1,329 @@
+"""Device class for Homevolt EMS devices."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import aiohttp
+
+from .const import DEVICE_MAP, ENDPOINT_EMS, ENDPOINT_SCHEDULE, SCHEDULE_TYPE
+from .exceptions import (
+    HomevoltAuthenticationError,
+    HomevoltConnectionError,
+    HomevoltDataError,
+)
+from .models import DeviceMetadata, Sensor, SensorType
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class Device:
+    """Represents a Homevolt EMS device."""
+
+    def __init__(
+        self,
+        ip_address: str,
+        password: str | None,
+        websession: aiohttp.ClientSession,
+    ) -> None:
+        """Initialize the device.
+
+        Args:
+            ip_address: IP address of the Homevolt device
+            password: Optional password for authentication
+            websession: aiohttp ClientSession for making requests
+        """
+        self._ip_address = ip_address
+        self._password = password
+        self._websession = websession
+        self._auth = aiohttp.BasicAuth("admin", password) if password else None
+
+        self.device_id: str | None = None
+        self.sensors: dict[str, Sensor] = {}
+        self.device_metadata: dict[str, DeviceMetadata] = {}
+        self.current_schedule: dict[str, Any] | None = None
+
+    async def update_info(self) -> None:
+        """Fetch and update all device information."""
+        await self.fetch_ems_data()
+        await self.fetch_schedule_data()
+
+    async def fetch_ems_data(self) -> None:
+        """Fetch EMS data from the device."""
+        try:
+            url = f"http://{self._ip_address}{ENDPOINT_EMS}"
+            async with self._websession.get(url, auth=self._auth) as response:
+                if response.status == 401:
+                    raise HomevoltAuthenticationError("Authentication failed")
+                response.raise_for_status()
+                ems_data = await response.json()
+        except aiohttp.ClientError as err:
+            raise HomevoltConnectionError(f"Failed to connect to device: {err}") from err
+        except Exception as err:
+            raise HomevoltDataError(f"Failed to parse EMS data: {err}") from err
+
+        self._parse_ems_data(ems_data)
+
+    async def fetch_schedule_data(self) -> None:
+        """Fetch schedule data from the device."""
+        try:
+            url = f"http://{self._ip_address}{ENDPOINT_SCHEDULE}"
+            async with self._websession.get(url, auth=self._auth) as response:
+                if response.status == 401:
+                    raise HomevoltAuthenticationError("Authentication failed")
+                response.raise_for_status()
+                schedule_data = await response.json()
+        except aiohttp.ClientError as err:
+            raise HomevoltConnectionError(f"Failed to connect to device: {err}") from err
+        except Exception as err:
+            raise HomevoltDataError(f"Failed to parse schedule data: {err}") from err
+
+        self._parse_schedule_data(schedule_data)
+
+    def _parse_ems_data(self, ems_data: dict[str, Any]) -> None:
+        """Parse EMS JSON response."""
+        if not ems_data.get("ems") or not ems_data["ems"]:
+            raise HomevoltDataError("No EMS data found in response")
+
+        device_id = str(ems_data["ems"][0]["ecu_id"])
+        self.device_id = device_id
+        ems_device_id = f"ems_{device_id}"
+
+        # Initialize device metadata
+        self.device_metadata = {
+            ems_device_id: DeviceMetadata(name=f"Homevolt EMS {device_id}", model="Homevolt EMS"),
+            "grid": DeviceMetadata(name="Homevolt Grid Sensor", model="Grid Sensor"),
+            "solar": DeviceMetadata(name="Homevolt Solar Sensor", model="Solar Sensor"),
+            "load": DeviceMetadata(name="Homevolt Load Sensor", model="Load Sensor"),
+        }
+
+        # Initialize sensors dictionary
+        self.sensors = {}
+
+        # EMS device sensors - all main EMS data
+        ems = ems_data["ems"][0]
+        self.sensors.update(
+            {
+                "L1 Voltage": Sensor(
+                    value=ems["ems_voltage"]["l1"] / 10,
+                    type=SensorType.VOLTAGE,
+                    device_identifier=ems_device_id,
+                ),
+                "L2 Voltage": Sensor(
+                    value=ems["ems_voltage"]["l2"] / 10,
+                    type=SensorType.VOLTAGE,
+                    device_identifier=ems_device_id,
+                ),
+                "L3 Voltage": Sensor(
+                    value=ems["ems_voltage"]["l3"] / 10,
+                    type=SensorType.VOLTAGE,
+                    device_identifier=ems_device_id,
+                ),
+                "L1_L2 Voltage": Sensor(
+                    value=ems["ems_voltage"]["l1_l2"] / 10,
+                    type=SensorType.VOLTAGE,
+                    device_identifier=ems_device_id,
+                ),
+                "L2_L3 Voltage": Sensor(
+                    value=ems["ems_voltage"]["l2_l3"] / 10,
+                    type=SensorType.VOLTAGE,
+                    device_identifier=ems_device_id,
+                ),
+                "L3_L1 Voltage": Sensor(
+                    value=ems["ems_voltage"]["l3_l1"] / 10,
+                    type=SensorType.VOLTAGE,
+                    device_identifier=ems_device_id,
+                ),
+                "L1 Current": Sensor(
+                    value=ems["ems_current"]["l1"],
+                    type=SensorType.CURRENT,
+                    device_identifier=ems_device_id,
+                ),
+                "L2 Current": Sensor(
+                    value=ems["ems_current"]["l2"],
+                    type=SensorType.CURRENT,
+                    device_identifier=ems_device_id,
+                ),
+                "L3 Current": Sensor(
+                    value=ems["ems_current"]["l3"],
+                    type=SensorType.CURRENT,
+                    device_identifier=ems_device_id,
+                ),
+                "System Temperature": Sensor(
+                    value=ems["ems_data"]["sys_temp"] / 10.0,
+                    type=SensorType.TEMPERATURE,
+                    device_identifier=ems_device_id,
+                ),
+                "Imported Energy": Sensor(
+                    value=ems["ems_aggregate"]["imported_kwh"],
+                    type=SensorType.ENERGY_INCREASING,
+                    device_identifier=ems_device_id,
+                ),
+                "Exported Energy": Sensor(
+                    value=ems["ems_aggregate"]["exported_kwh"],
+                    type=SensorType.ENERGY_INCREASING,
+                    device_identifier=ems_device_id,
+                ),
+                "Available Charging Power": Sensor(
+                    value=ems["ems_prediction"]["avail_ch_pwr"],
+                    type=SensorType.POWER,
+                    device_identifier=ems_device_id,
+                ),
+                "Available Discharge Power": Sensor(
+                    value=ems["ems_prediction"]["avail_di_pwr"],
+                    type=SensorType.POWER,
+                    device_identifier=ems_device_id,
+                ),
+                "Available Charging Energy": Sensor(
+                    value=ems["ems_prediction"]["avail_ch_energy"],
+                    type=SensorType.ENERGY_TOTAL,
+                    device_identifier=ems_device_id,
+                ),
+                "Available Discharge Energy": Sensor(
+                    value=ems["ems_prediction"]["avail_di_energy"],
+                    type=SensorType.ENERGY_TOTAL,
+                    device_identifier=ems_device_id,
+                ),
+                "Power": Sensor(
+                    value=ems["ems_data"]["power"],
+                    type=SensorType.POWER,
+                    device_identifier=ems_device_id,
+                ),
+                "Frequency": Sensor(
+                    value=ems["ems_data"]["frequency"],
+                    type=SensorType.FREQUENCY,
+                    device_identifier=ems_device_id,
+                ),
+                "Battery State of Charge": Sensor(
+                    value=ems["ems_data"]["soc_avg"] / 100,
+                    type=SensorType.PERCENTAGE,
+                    device_identifier=ems_device_id,
+                ),
+            }
+        )
+
+        # Battery sensors
+        for bat_id, battery in enumerate(ems.get("bms_data", [])):
+            battery_device_id = f"battery_{bat_id}"
+            self.device_metadata[battery_device_id] = DeviceMetadata(
+                name=f"Homevolt Battery {bat_id}",
+                model="Homevolt Battery",
+            )
+            self.sensors[f"Homevolt battery {bat_id}"] = Sensor(
+                value=battery["soc"] / 100,
+                type=SensorType.PERCENTAGE,
+                device_identifier=battery_device_id,
+            )
+            self.sensors[f"Homevolt battery {bat_id} tmin"] = Sensor(
+                value=battery["tmin"] / 10,
+                type=SensorType.TEMPERATURE,
+                device_identifier=battery_device_id,
+            )
+            self.sensors[f"Homevolt battery {bat_id} tmax"] = Sensor(
+                value=battery["tmax"] / 10,
+                type=SensorType.TEMPERATURE,
+                device_identifier=battery_device_id,
+            )
+            self.sensors[f"Homevolt battery {bat_id} charge cycles"] = Sensor(
+                value=battery["cycle_count"],
+                type=SensorType.COUNT,
+                device_identifier=battery_device_id,
+            )
+
+        # External sensors (grid, solar, load)
+        for sensor in ems_data.get("sensors", []):
+            if not sensor.get("available"):
+                continue
+
+            sensor_type = sensor["type"]
+            sensor_device_id = DEVICE_MAP.get(sensor_type)
+
+            if not sensor_device_id:
+                continue
+
+            # Calculate total power from all phases
+            total_power = sum(phase["power"] for phase in sensor.get("phase", []))
+
+            self.sensors[f"Power {sensor_type}"] = Sensor(
+                value=total_power,
+                type=SensorType.POWER,
+                device_identifier=sensor_device_id,
+            )
+            self.sensors[f"Energy imported {sensor_type}"] = Sensor(
+                value=sensor.get("energy_imported", 0),
+                type=SensorType.ENERGY_INCREASING,
+                device_identifier=sensor_device_id,
+            )
+            self.sensors[f"Energy exported {sensor_type}"] = Sensor(
+                value=sensor.get("energy_exported", 0),
+                type=SensorType.ENERGY_INCREASING,
+                device_identifier=sensor_device_id,
+            )
+            self.sensors[f"RSSI {sensor_type}"] = Sensor(
+                value=sensor.get("rssi"),
+                type=SensorType.SIGNAL_STRENGTH,
+                device_identifier=sensor_device_id,
+            )
+            self.sensors[f"Average RSSI {sensor_type}"] = Sensor(
+                value=sensor.get("average_rssi"),
+                type=SensorType.SIGNAL_STRENGTH,
+                device_identifier=sensor_device_id,
+            )
+
+            # Phase-specific sensors
+            for phase_name, phase in zip(["L1", "L2", "L3"], sensor.get("phase", []), strict=False):
+                self.sensors[f"{phase_name} Voltage {sensor_type}"] = Sensor(
+                    value=phase.get("voltage"),
+                    type=SensorType.VOLTAGE,
+                    device_identifier=sensor_device_id,
+                )
+                self.sensors[f"{phase_name} Current {sensor_type}"] = Sensor(
+                    value=phase.get("amp"),
+                    type=SensorType.CURRENT,
+                    device_identifier=sensor_device_id,
+                )
+                self.sensors[f"{phase_name} Power {sensor_type}"] = Sensor(
+                    value=phase.get("power"),
+                    type=SensorType.POWER,
+                    device_identifier=sensor_device_id,
+                )
+
+    def _parse_schedule_data(self, schedule_data: dict[str, Any]) -> None:
+        """Parse schedule JSON response."""
+        self.current_schedule = schedule_data
+
+        if not self.device_id:
+            return
+
+        ems_device_id = f"ems_{self.device_id}"
+
+        self.sensors["Schedule id"] = Sensor(
+            value=schedule_data.get("schedule_id"),
+            type=SensorType.TEXT,
+            device_identifier=ems_device_id,
+        )
+
+        schedule = schedule_data.get("schedule", [{}])[0] if schedule_data.get("schedule") else {"type": -1, "params": {}}
+
+        self.sensors["Schedule Type"] = Sensor(
+            value=SCHEDULE_TYPE.get(schedule.get("type", -1)),
+            type=SensorType.SCHEDULE_TYPE,
+            device_identifier=ems_device_id,
+        )
+        self.sensors["Schedule Power Setpoint"] = Sensor(
+            value=schedule.get("params", {}).get("setpoint"),
+            type=SensorType.POWER,
+            device_identifier=ems_device_id,
+        )
+        self.sensors["Schedule Max Power"] = Sensor(
+            value=schedule.get("max_charge"),
+            type=SensorType.POWER,
+            device_identifier=ems_device_id,
+        )
+        self.sensors["Schedule Max Discharge"] = Sensor(
+            value=schedule.get("max_discharge"),
+            type=SensorType.POWER,
+            device_identifier=ems_device_id,
+        )
+

homevolt-0.1.0/homevolt/exceptions.py

@@ -0,0 +1,26 @@
+"""Custom exceptions for the Homevolt library."""
+
+
+class HomevoltException(Exception):
+    """Base exception for all Homevolt errors."""
+
+    pass
+
+
+class HomevoltConnectionError(HomevoltException):
+    """Raised when there's a connection or network error."""
+
+    pass
+
+
+class HomevoltAuthenticationError(HomevoltException):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class HomevoltDataError(HomevoltException):
+    """Raised when there's an error parsing or processing data."""
+
+    pass
+

homevolt-0.1.0/homevolt/homevolt.py

@@ -0,0 +1,82 @@
+"""Main Homevolt class for connecting to EMS devices."""
+
+from __future__ import annotations
+
+import logging
+
+import aiohttp
+
+from .device import Device
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class Homevolt:
+    """Main class for interacting with Homevolt EMS devices."""
+
+    def __init__(
+        self,
+        ip_address: str,
+        password: str | None = None,
+        websession: aiohttp.ClientSession | None = None,
+    ) -> None:
+        """Initialize the Homevolt connection.
+
+        Args:
+            ip_address: IP address of the Homevolt device
+            password: Optional password for authentication
+            websession: Optional aiohttp ClientSession. If not provided, one will be created.
+        """
+        self._ip_address = ip_address
+        self._password = password
+        self._websession = websession
+        self._own_session = websession is None
+
+        self._device: Device | None = None
+
+    async def update_info(self) -> None:
+        """Fetch and update device information."""
+        if self._device is None:
+            await self._ensure_session()
+            self._device = Device(
+                ip_address=self._ip_address,
+                password=self._password,
+                websession=self._websession,
+            )
+
+        await self._device.update_info()
+
+    def get_device(self) -> Device:
+        """Get the device object.
+
+        Returns:
+            The Device object for this Homevolt connection
+
+        Raises:
+            RuntimeError: If device information hasn't been fetched yet
+        """
+        if self._device is None:
+            raise RuntimeError("Device information not yet fetched. Call update_info() first.")
+        return self._device
+
+    async def close_connection(self) -> None:
+        """Close the connection and clean up resources."""
+        if self._own_session and self._websession:
+            await self._websession.close()
+            self._websession = None
+
+    async def _ensure_session(self) -> None:
+        """Ensure a websession exists."""
+        if self._websession is None:
+            self._websession = aiohttp.ClientSession()
+            self._own_session = True
+
+    async def __aenter__(self) -> Homevolt:
+        """Async context manager entry."""
+        await self._ensure_session()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Async context manager exit."""
+        await self.close_connection()
+

homevolt-0.1.0/homevolt/models.py

@@ -0,0 +1,43 @@
+"""Data models for Homevolt library."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+@dataclass
+class DeviceMetadata:
+    """Metadata for device information."""
+
+    name: str
+    model: str
+
+
+class SensorType(Enum):
+    """Enumeration of sensor types."""
+
+    COUNT = "count"
+    CURRENT = "current"
+    ENERGY_INCREASING = "energy_increasing"
+    ENERGY_TOTAL = "energy_total"
+    ENERGY = "energy"
+    FREQUENCY = "frequency"
+    POWER = "power"
+    VOLTAGE = "voltage"
+    SIGNAL_STRENGTH = "signal_strength"
+    PERCENTAGE = "percentage"
+    SCHEDULE_TYPE = "schedule_type"
+    SCHEDULE_PARAMS = "schedule_params"
+    TEMPERATURE = "temperature"
+    TEXT = "text"
+
+
+@dataclass
+class Sensor:
+    """Represents a sensor reading."""
+
+    value: float | str | None
+    type: SensorType
+    device_identifier: str = "main"  # Device identifier for grouping sensors into devices
+

homevolt-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "Homevolt"
+version = "0.1.0"
+description = "Python library for Homevolt EMS devices"
+readme = "README.md"
+requires-python = ">=3.12"
+license = {text = "GPL-3.0"}
+authors = [
+    {name = "Your Name", email = "your.email@example.com"},
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "aiohttp>=3.8.0",
+]
+
+[project.optional-dependencies]
+
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["homevolt*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+ignore = ["E501"]
+

homevolt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+