python-openevse-http 0.0.0__py3-none-any.whl

openevsehttp/sensors.py

@@ -0,0 +1,137 @@
+"""Sensor data posting methods for the OpenEVSE charger."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from typing import Any
+
+from .const import BAT_LVL, BAT_RANGE, GRID, SOLAR, TTF, VOLTAGE
+from .exceptions import UnsupportedFeature
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class SensorsMixin:
+    """Mixin providing sensor data posting methods for OpenEVSE."""
+
+    url: str
+
+    # These are defined in client.py
+    def _version_check(self, min_version: str, max_version: str = "") -> bool:
+        raise NotImplementedError
+
+    async def process_request(
+        self, url: str, method: str = "", data: Any = None, rapi: Any = None
+    ) -> Mapping[str, Any] | list[Any] | str:
+        raise NotImplementedError
+
+    def _normalize_response(self, response: Any) -> dict[str, Any] | list[Any]:
+        """Normalize response to a dict or list."""
+        raise NotImplementedError
+
+    # HTTP Posting of grid voltage
+    async def grid_voltage(self, voltage: int | None = None) -> None:
+        """Send pushed sensor data to grid voltage."""
+        if not self._version_check("2.9.1"):
+            _LOGGER.debug("Feature not supported for older firmware.")
+            raise UnsupportedFeature
+
+        url = f"{self.url}status"
+        data = {}
+
+        if voltage is not None:
+            data[VOLTAGE] = voltage
+
+        if not data:
+            _LOGGER.info("No sensor data to send to device.")
+        else:
+            _LOGGER.debug("Posting voltage: %s", data)
+            response = await self.process_request(url=url, method="post", data=data)
+            _LOGGER.debug(
+                "Voltage posting response: %s", self._normalize_response(response)
+            )
+
+    # Self production HTTP Posting
+    async def self_production(
+        self,
+        grid: int | None = None,
+        solar: int | None = None,
+        invert: bool = True,
+        voltage: int | None = None,
+    ) -> None:
+        """Send pushed sensor data to self-production."""
+        if not self._version_check("2.9.1"):
+            _LOGGER.debug("Feature not supported for older firmware.")
+            raise UnsupportedFeature
+
+        # Invert the sensor -import/+export
+        if invert and grid is not None:
+            grid = grid * -1
+
+        url = f"{self.url}status"
+        data = {}
+
+        # Prefer grid sensor data
+        if grid is not None:
+            data[GRID] = grid
+        elif solar is not None:
+            data[SOLAR] = solar
+        if voltage is not None:
+            data[VOLTAGE] = voltage
+
+        if not data:
+            _LOGGER.info("No sensor data to send to device.")
+        else:
+            _LOGGER.debug("Posting self-production: %s", data)
+            response = await self.process_request(url=url, method="post", data=data)
+            _LOGGER.debug(
+                "Self-production response: %s", self._normalize_response(response)
+            )
+
+    # State of charge HTTP posting
+    async def soc(
+        self,
+        battery_level: int | None = None,
+        battery_range: int | None = None,
+        time_to_full: int | None = None,
+        voltage: int | None = None,
+    ) -> None:
+        """Send pushed sensor data to State of Charge."""
+        if not self._version_check("4.1.0"):
+            _LOGGER.debug("Feature not supported for older firmware.")
+            raise UnsupportedFeature
+
+        url = f"{self.url}status"
+        data = {}
+
+        # Build post data
+        if battery_level is not None:
+            data[BAT_LVL] = battery_level
+        if battery_range is not None:
+            data[BAT_RANGE] = battery_range
+        if time_to_full is not None:
+            data[TTF] = time_to_full
+        if voltage is not None:
+            data[VOLTAGE] = voltage
+
+        if not data:
+            _LOGGER.info("No SOC data to send to device.")
+        else:
+            _LOGGER.debug("Posting SOC data: %s", data)
+            response = await self.process_request(url=url, method="post", data=data)
+            _LOGGER.debug("SOC response: %s", self._normalize_response(response))
+
+    # Shaper HTTP Posting
+    async def set_shaper_live_pwr(self, power: int) -> None:
+        """Send pushed sensor data to shaper."""
+        if not self._version_check("4.0.0"):
+            _LOGGER.debug("Feature not supported for older firmware.")
+            raise UnsupportedFeature
+
+        url = f"{self.url}status"
+        data = {"shaper_live_pwr": power}
+
+        _LOGGER.debug("Posting shaper data: %s", data)
+        response = await self.process_request(url=url, method="post", data=data)
+        _LOGGER.debug("Shaper response: %s", self._normalize_response(response))

openevsehttp/utils.py

@@ -0,0 +1,29 @@
+"""Utility functions for python-openevse-http."""
+
+import logging
+import re
+
+from awesomeversion import AwesomeVersion
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def normalize_version(version: str) -> str:
+    """Normalize the version string to strip 'dev' tag."""
+    if "dev" in version:
+        _LOGGER.debug("Stripping 'dev' from version.")
+        value = version.split(".")
+        return ".".join(value[0:3])
+    return version
+
+
+def get_awesome_version(version: str) -> AwesomeVersion:
+    """Parse and normalize the version string, returning an AwesomeVersion."""
+    if "master" in version:
+        version = "dev"
+    value = normalize_version(version)
+    if "dev" not in version:
+        firmware_search = re.search(r"\d+\.\d+\.\d+", value)
+        if firmware_search:
+            value = firmware_search.group(0)
+    return AwesomeVersion(value)

openevsehttp/websocket.py

@@ -0,0 +1,275 @@
+"""Websocket class for OpenEVSE HTTP."""
+
+import asyncio
+import datetime
+import inspect
+import logging
+
+import aiohttp
+
+_LOGGER = logging.getLogger(__name__)
+
+MAX_FAILED_ATTEMPTS = 5
+
+ERROR_AUTH_FAILURE = "Authorization failure"
+ERROR_TOO_MANY_RETRIES = "Too many retries"
+ERROR_UNKNOWN = "Unknown"
+ERROR_PING_TIMEOUT = "No pong reply"
+
+SIGNAL_CONNECTION_STATE = "websocket_state"
+STATE_CONNECTED = "connected"
+STATE_DISCONNECTED = "disconnected"
+STATE_STARTING = "starting"
+STATE_STOPPED = "stopped"
+
+
+class OpenEVSEWebsocket:
+    """Represent a websocket connection to a OpenEVSE charger."""
+
+    def __init__(
+        self,
+        server,
+        callback,
+        user=None,
+        password=None,
+        session: aiohttp.ClientSession | None = None,
+    ):
+        """Initialize a OpenEVSEWebsocket instance."""
+        self.session = session
+        self._session_external = session is not None
+        self.uri = self._get_uri(server)
+        self._user = user
+        self._password = password
+        self.callback = callback
+        self._state = STATE_DISCONNECTED
+        self.failed_attempts = 0
+        self._error_reason = None
+        self._client = None
+        self._ping = None
+        self._pong = None
+        self._tasks: set[asyncio.Task] = set()
+        self._listener_loop: asyncio.AbstractEventLoop | None = None
+
+    @property
+    def state(self):
+        """Return the current state."""
+        return self._state
+
+    @state.setter
+    def state(self, value):
+        """Setter that schedules the callback."""
+        self._state = value
+        _LOGGER.debug("Websocket %s", value)
+
+        if not self.callback:
+            self._error_reason = None
+            return
+
+        # Prepare the coroutine or invoke the callback
+        coro = self.callback(SIGNAL_CONNECTION_STATE, value, self._error_reason)
+
+        if not inspect.isawaitable(coro):
+            self._error_reason = None
+            return
+
+        try:
+            if self._listener_loop:
+                self._listener_loop.call_soon_threadsafe(self._schedule_task, coro)
+            else:
+                try:
+                    task = asyncio.ensure_future(coro)
+                    self._tasks.add(task)
+                    task.add_done_callback(self._tasks.discard)
+                except RuntimeError:
+                    # Fallback to get_event_loop if ensure_future fails and no _listener_loop
+                    loop = asyncio.get_event_loop()
+                    loop.call_soon_threadsafe(self._schedule_task, coro)
+        except RuntimeError:
+            _LOGGER.error("Failed to schedule callback from sync context: %s", coro)
+            if hasattr(coro, "close"):
+                coro.close()
+        self._error_reason = None
+
+    def _schedule_task(self, coro):
+        """Schedule a task from a thread-safe context."""
+        try:
+            task = asyncio.ensure_future(coro)
+            self._tasks.add(task)
+            task.add_done_callback(self._tasks.discard)
+        except RuntimeError:
+            _LOGGER.error("Failed to schedule callback task: %s", coro)
+            # If we still can't schedule it, we must at least close the coroutine
+            # to avoid RuntimeWarning: coroutine '...' was never awaited
+            if hasattr(coro, "close"):
+                coro.close()
+
+    async def _set_state(self, value):
+        """Async helper to set the state and await the callback."""
+        self._state = value
+        _LOGGER.debug("Websocket %s", value)
+        if self.callback:
+            result = self.callback(SIGNAL_CONNECTION_STATE, value, self._error_reason)
+            if inspect.isawaitable(result):
+                await result
+        self._error_reason = None
+
+    @staticmethod
+    def _get_uri(server):
+        """Generate the websocket URI."""
+        return server[: server.rfind("/")].replace("http", "ws") + "/ws"
+
+    async def running(self):
+        """Open a persistent websocket connection and act on events."""
+        await self._ensure_session()
+        await self._set_state(STATE_STARTING)
+        auth = None
+
+        if self._user and self._password:
+            auth = aiohttp.BasicAuth(self._user, self._password)
+
+        try:
+            async with self.session.ws_connect(
+                self.uri,
+                heartbeat=15,
+                auth=auth,
+            ) as ws_client:
+                self._client = ws_client
+                await self._set_state(STATE_CONNECTED)
+                self.failed_attempts = 0
+                await self._handle_messages(ws_client)
+
+        except aiohttp.ClientResponseError as error:
+            await self._handle_response_error(error)
+        except (aiohttp.ClientConnectionError, asyncio.TimeoutError) as error:
+            await self._handle_connection_error(error)
+        except Exception as error:  # pylint: disable=broad-except
+            if self.state != STATE_STOPPED:
+                _LOGGER.exception("Unexpected exception occurred: %s", error)
+                self._error_reason = error
+                await self._set_state(STATE_STOPPED)
+        else:
+            if self.state != STATE_STOPPED:
+                await self._set_state(STATE_DISCONNECTED)
+                await asyncio.sleep(5)
+        finally:
+            if self._client is not None:
+                await self._client.close()
+                self._client = None
+
+    async def _handle_messages(self, ws_client):
+        """Handle incoming websocket messages."""
+        async for message in ws_client:
+            if self.state == STATE_STOPPED:
+                break
+
+            if message.type == aiohttp.WSMsgType.TEXT:
+                msg = message.json()
+                if isinstance(msg, dict) and "pong" in msg:
+                    self._pong = datetime.datetime.now()
+                    if len(msg) == 1:
+                        # Pure pong frame, skip callback
+                        continue
+
+                msgtype = "data"
+                if self.callback:
+                    result = self.callback(msgtype, msg, None)
+                    if inspect.isawaitable(result):
+                        await result
+
+            elif message.type in (aiohttp.WSMsgType.CLOSED, aiohttp.WSMsgType.ERROR):
+                if message.type == aiohttp.WSMsgType.CLOSED:
+                    _LOGGER.warning("Websocket connection closed")
+                else:
+                    _LOGGER.error("Websocket error")
+                break
+
+    async def _handle_response_error(self, error):
+        """Handle ClientResponseError."""
+        if error.status == 401:
+            _LOGGER.error("Credentials rejected: %s", error)
+            self._error_reason = ERROR_AUTH_FAILURE
+        else:
+            _LOGGER.error("Unexpected response received: %s", error)
+            self._error_reason = error
+        await self._set_state(STATE_STOPPED)
+
+    async def _handle_connection_error(self, error):
+        """Handle connection errors."""
+        self.failed_attempts += 1
+        if self.failed_attempts > MAX_FAILED_ATTEMPTS:
+            self._error_reason = ERROR_TOO_MANY_RETRIES
+            await self._set_state(STATE_STOPPED)
+        elif self.state != STATE_STOPPED:
+            retry_delay = min(2 ** (self.failed_attempts - 1) * 30, 300)
+            _LOGGER.error(
+                "Websocket connection failed, retrying in %ds: %s",
+                retry_delay,
+                error,
+            )
+            await self._set_state(STATE_DISCONNECTED)
+            await asyncio.sleep(retry_delay)
+
+    async def listen(self):
+        """Start the listening websocket."""
+        await self._ensure_session()
+        self.failed_attempts = 0
+        self._listener_loop = asyncio.get_running_loop()
+        try:
+            while self.state != STATE_STOPPED:
+                await self.running()
+        finally:
+            self._listener_loop = None
+
+    async def _ensure_session(self):
+        """Ensure aiohttp.ClientSession exists."""
+        if self.session is None:
+            self.session = aiohttp.ClientSession()
+            self._session_external = False
+
+    async def close(self):
+        """Close the listening websocket."""
+        await self._set_state(STATE_STOPPED)
+
+        if self._tasks:
+            for task in self._tasks:
+                task.cancel()
+            await asyncio.gather(*self._tasks, return_exceptions=True)
+            self._tasks.clear()
+
+        if self._client is not None:
+            await self._client.close()
+            self._client = None
+        # Only close the session if we created it
+        if not self._session_external and self.session is not None:
+            await self.session.close()
+            self.session = None
+
+    async def keepalive(self):
+        """Send ping requests to websocket."""
+        if self._ping and self._pong:
+            time_delta = self._pong - self._ping
+            if time_delta < datetime.timedelta(0):
+                # Negative time should indicate no pong reply so consider the
+                # websocket disconnected.
+                self._error_reason = ERROR_PING_TIMEOUT
+                await self._set_state(STATE_DISCONNECTED)
+
+        data = {"ping": 1}
+        _LOGGER.debug("Sending message: %s to websocket.", data)
+        try:
+            if self._client:
+                await self._client.send_json(data)
+                self._ping = datetime.datetime.now()
+                _LOGGER.debug("Ping message sent.")
+            else:
+                _LOGGER.warning("Websocket client not found.")
+        except TypeError as err:
+            _LOGGER.error("Attempt to send ping data failed: %s", err)
+        except ValueError as err:
+            _LOGGER.error("Error parsing data: %s", err)
+        except RuntimeError as err:
+            _LOGGER.debug("Websocket connection issue: %s", err)
+            await self._set_state(STATE_DISCONNECTED)
+        except Exception as err:  # pylint: disable=broad-exception-caught
+            _LOGGER.debug("Problem sending ping request: %s", err)
+            await self._set_state(STATE_DISCONNECTED)

python_openevse_http-0.0.0.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: python_openevse_http
+Version: 0.0.0
+Summary: Python wrapper for OpenEVSE HTTP API
+Home-page: https://github.com/firstof9/python-openevse-http
+Download-URL: https://github.com/firstof9/python-openevse-http
+Author: firstof9
+Author-email: firstof9@gmail.com
+License: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: Apache Software License
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: download-url
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+![Codecov branch](https://img.shields.io/codecov/c/github/firstof9/python-openevse-http/main?style=flat-square)
+![GitHub commit activity (branch)](https://img.shields.io/github/commit-activity/m/firstof9/python-openevse-http?style=flat-square)
+![GitHub last commit](https://img.shields.io/github/last-commit/firstof9/python-openevse-http?style=flat-square)
+![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/firstof9/python-openevse-http?style=flat-square)
+
+# python-openevse-http
+
+A Python library for communicating with [OpenEVSE](https://www.openevse.com/) chargers via the HTTP API on ESP8266 and ESP32-based WiFi modules.
+
+## Features
+
+- **Asynchronous**: Built on `aiohttp` for non-blocking I/O.
+- **WebSocket Support**: Real-time updates for charger status.
+- **Firmware Support**: Compatible with ESP8266 (2.x) and ESP32 (4.x+) WiFi firmware.
+- **Comprehensive API**:
+    - Query status and configuration.
+    - Manage manual overrides.
+    - Control charging claims and limits.
+    - Handle schedules.
+    - **Shaper Toggle**: Enable or disable the grid shaper feature (requires firmware 4.0.0+).
+
+## Installation
+
+```bash
+pip install python_openevse_http
+```
+
+## Quick Start
+
+```python
+import asyncio
+from openevsehttp import OpenEVSE
+
+async def main():
+    # Initialize the charger
+    charger = OpenEVSE("192.168.1.30")
+
+    # Update state
+    await charger.update()
+
+    print(f"Charger State: {charger.status}")
+    print(f"Current Charge: {charger.charge_current}A")
+
+    # Toggle the Shaper feature
+    if charger.shaper_active:
+        print("Shaper is active, disabling...")
+    else:
+        print("Shaper is inactive, enabling...")
+
+    await charger.toggle_shaper()
+
+    # Clean up
+    await charger.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## API Support Matrix
+
+| Endpoint | Methods | Supported | Description |
+| :--- | :--- | :---: | :--- |
+| `/status` | GET, POST | ✅ | Real-time status, sensors, and **Vehicle SoC** pushing |
+| `/config` | GET, POST | ✅ | System and WiFi configuration |
+| `/override` | GET, POST, PATCH, DELETE | ✅ | Manual charging overrides & current limits |
+| `/claims` | GET, POST, DELETE | ✅ | Client-based charging claims |
+| `/schedule` | GET, POST | ✅ | Charging schedule management |
+| `/limit` | GET, POST, DELETE | ✅ | Charge limits (Time, Energy, SoC) |
+| `/shaper` | POST | ✅ | Grid shaper control (v4.0.0+) |
+| `/restart` | POST | ✅ | Reboot WiFi gateway or EVSE module |
+| `/divertmode` | POST | ✅ | Solar divert mode control |
+| `/r` (RAPI) | POST | ✅ | Direct RAPI command interface |
+| `/ws` | GET | ✅ | WebSocket real-time updates |
+| `/time` | GET, POST | ❌ | RTC and NTP time settings |
+| `/logs` | GET | ❌ | System and debug event logs |
+| `/emeter` | DELETE | ❌ | Energy meter reset |
+| `/wifi` | GET, POST | ❌ | Network scanning and AP configuration |
+| `/tesla` | GET | ❌ | Tesla vehicle integration |
+| `/certificates`| GET, POST, DELETE | ❌ | SSL/TLS certificate management |
+| `/schedule/plan`| GET | ❌ | Schedule planning and optimization |
+| `/update` | POST | ❌ | Firmware update interface |
+| `/rfid/add` | POST | ❌ | RFID tag management |
+
+✅ = Fully Supported \| ⚠️ = Partial Support \| ❌ = Not yet implemented
+
+## License
+
+This project is licensed under the Apache-2.0 License.

python_openevse_http-0.0.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+openevsehttp/__init__.py,sha256=I6a1mjOZHYiWb_qfCuDuFLOOncrkkB_7uwybtOIujfY,1165
+openevsehttp/__main__.py,sha256=EHmSdT7GjAVvHQxvLBTjZXsj_V5SB6B2_kpgUAT7mPM,146
+openevsehttp/client.py,sha256=JBAC1jJGdzOabVAqHv8x6EJDVjhaW4t7Iwqn4lDWhwE,17502
+openevsehttp/commands.py,sha256=lANhgVhtJJlQxLwFlMrxk3DrmnY2bXK5h4z3o9o6ZEk,20617
+openevsehttp/const.py,sha256=y-2hGv_PCal_-VCSGC7IIyzQYtfeVdq3MjOhBWIdZvc,1440
+openevsehttp/exceptions.py,sha256=bqz-tHTW1AYJMKcm0s5M6z5tA6XZgjnCiBLW1XrZ_70,672
+openevsehttp/managers.py,sha256=kEX1ZD9u-FY0UEZJsxeFEGBSGzSlkbBc0kmxCiMJtJw,5373
+openevsehttp/properties.py,sha256=QVSyn_5a7vI1b4TdnnToRdw6veVCfnp7a19VYit95hg,17107
+openevsehttp/sensors.py,sha256=sJP2FPnU1Lk5S3VUyFT14JM1nKEBQPsjl-DiZI-pZrs,4673
+openevsehttp/utils.py,sha256=e3HH_jwZgb1iBWJgIoMOM0JPrQNwXyVdOx5vTWOh4T0,858
+openevsehttp/websocket.py,sha256=Mi_WFmlT3-9i6bbHIN6ua09SD8CpIle2vRXB3HyWzmM,10066
+python_openevse_http-0.0.0.dist-info/licenses/LICENSE,sha256=hSB6TOQ7rmwSGb6XzqRjDGMvmUj5_GlacqQin3tegtA,11341
+python_openevse_http-0.0.0.dist-info/METADATA,sha256=iC4mhS9bDUxzmip1gDyiuDFohEkeJTWmfjL_FNTP5sA,4363
+python_openevse_http-0.0.0.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
+python_openevse_http-0.0.0.dist-info/top_level.txt,sha256=u8RUkoEIE33Cjn6gmqiEoVpZ0VZ59WJ3FXBwwOg0CPE,13
+python_openevse_http-0.0.0.dist-info/RECORD,,

python_openevse_http-0.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (79.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+