pyiont 0.1.0__tar.gz

pyiont-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.coverage
+coverage.xml
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

pyiont-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IONT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyiont-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: pyiont
+Version: 0.1.0
+Summary: Asynchronous Python client for IONT EV chargers over Modbus TCP.
+Project-URL: Homepage, https://github.com/IONTtech/pyiont
+Project-URL: Repository, https://github.com/IONTtech/pyiont
+Project-URL: Documentation, https://github.com/IONTtech/pyiont
+Project-URL: Bug Tracker, https://github.com/IONTtech/pyiont/issues
+Project-URL: Changelog, https://github.com/IONTtech/pyiont/releases
+Author-email: IONT <info@iont.tech>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: async,ev-charger,evse,home-assistant,iont,modbus,wallbox
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: modbus-connection>=4.8.1
+Provides-Extra: pymodbus
+Requires-Dist: modbus-connection[pymodbus]>=4.8.1; extra == 'pymodbus'
+Provides-Extra: tmodbus
+Requires-Dist: modbus-connection[tmodbus]>=4.8.1; extra == 'tmodbus'
+Description-Content-Type: text/markdown
+
+# pyiont
+
+Asynchronous Python client for [IONT](https://iont.tech) EV chargers over
+Modbus TCP.
+
+The library is built on [modbus-connection](https://github.com/home-assistant-libs/modbus-connection):
+it takes a `ModbusUnit`, maps the charger's register blocks to typed
+attributes, and exposes the commands the charger accepts. It has no Home
+Assistant dependency and is the device layer of the Home Assistant `iont`
+integration.
+
+## Install
+
+```bash
+pip install "pyiont[tmodbus]"    # tmodbus backend
+pip install "pyiont[pymodbus]"   # pymodbus backend
+```
+
+## Prerequisites
+
+Modbus TCP has to be enabled on the charger, in its administration interface
+under **Protocols**. Writing (authorization, power limit) is a separate switch
+there and is off by default. The charger listens on port `502`.
+
+## Example
+
+```python
+import asyncio
+
+from modbus_connection import ModbusTcpParams
+from modbus_connection.tmodbus import ModbusConnection
+
+from pyiont import IontCharger
+
+
+async def main() -> None:
+    connection = ModbusConnection(ModbusTcpParams(host="192.168.1.60", port=502))
+    try:
+        charger = await IontCharger.async_probe(connection.for_unit(1))
+        report = await charger.async_update()
+
+        print("Status:", charger.device.status.name.lower())
+        print("Available power:", charger.device.available_power, "W")
+        for number, connector in enumerate(charger.connectors, 1):
+            print(
+                f"Connector {number}:",
+                connector.charging_state.name.lower(),
+                connector.power,
+                "W",
+                connector.session_energy,
+                "Wh",
+            )
+        print("Failed sub-systems:", report.failed)
+
+        await charger.async_authorize(1)  # start charging on connector 1
+        await charger.async_set_external_power_limit(7_400)  # cap at 7.4 kW
+    finally:
+        await connection.close()
+
+
+asyncio.run(main())
+```
+
+## What it reads
+
+- **Device**: breaker limits, phase count, free-charging mode, user power
+  ceiling, available power, charging strategy, status, uptime, connector count.
+- **Settings**: the external power limit (writable).
+- **Connector** (one block per connector): connection and vehicle state,
+  charging state, authorization and its source, power, per-phase voltage,
+  current and frequency, session, last-session and lifetime energy, battery
+  state of charge (DC), inner and ambient temperature.
+
+`async_update()` reads each sub-system on its own and returns an
+`UpdateReport` naming what refreshed and what failed, so one silent connector
+does not blank the rest. A link that answers nothing raises
+`IontConnectionError`.
+
+## Commands
+
+- `async_authorize(number, boost=False)` / `async_deauthorize(number)`: start
+  or stop charging on a connector by its 1-based number. `boost=True` charges at
+  full available current even under the eco strategy.
+- `async_authorize_by_id(connector_id)` / `async_deauthorize_by_id(connector_id)`:
+  the same, addressing the connector by its OCPP connector ID.
+- `async_set_external_power_limit(watts)` / `async_clear_external_power_limit()`:
+  cap the charging power from outside, for example from a home energy manager.
+
+A command that the charger does not process in time, or reports a result
+other than success for, raises `IontCommandError`.
+
+## Develop
+
+```bash
+uv sync --extra tmodbus
+uv run pytest
+uv run mypy
+uv run ruff check
+```
+
+## License
+
+MIT

pyiont-0.1.0/README.md

@@ -0,0 +1,103 @@
+# pyiont
+
+Asynchronous Python client for [IONT](https://iont.tech) EV chargers over
+Modbus TCP.
+
+The library is built on [modbus-connection](https://github.com/home-assistant-libs/modbus-connection):
+it takes a `ModbusUnit`, maps the charger's register blocks to typed
+attributes, and exposes the commands the charger accepts. It has no Home
+Assistant dependency and is the device layer of the Home Assistant `iont`
+integration.
+
+## Install
+
+```bash
+pip install "pyiont[tmodbus]"    # tmodbus backend
+pip install "pyiont[pymodbus]"   # pymodbus backend
+```
+
+## Prerequisites
+
+Modbus TCP has to be enabled on the charger, in its administration interface
+under **Protocols**. Writing (authorization, power limit) is a separate switch
+there and is off by default. The charger listens on port `502`.
+
+## Example
+
+```python
+import asyncio
+
+from modbus_connection import ModbusTcpParams
+from modbus_connection.tmodbus import ModbusConnection
+
+from pyiont import IontCharger
+
+
+async def main() -> None:
+    connection = ModbusConnection(ModbusTcpParams(host="192.168.1.60", port=502))
+    try:
+        charger = await IontCharger.async_probe(connection.for_unit(1))
+        report = await charger.async_update()
+
+        print("Status:", charger.device.status.name.lower())
+        print("Available power:", charger.device.available_power, "W")
+        for number, connector in enumerate(charger.connectors, 1):
+            print(
+                f"Connector {number}:",
+                connector.charging_state.name.lower(),
+                connector.power,
+                "W",
+                connector.session_energy,
+                "Wh",
+            )
+        print("Failed sub-systems:", report.failed)
+
+        await charger.async_authorize(1)  # start charging on connector 1
+        await charger.async_set_external_power_limit(7_400)  # cap at 7.4 kW
+    finally:
+        await connection.close()
+
+
+asyncio.run(main())
+```
+
+## What it reads
+
+- **Device**: breaker limits, phase count, free-charging mode, user power
+  ceiling, available power, charging strategy, status, uptime, connector count.
+- **Settings**: the external power limit (writable).
+- **Connector** (one block per connector): connection and vehicle state,
+  charging state, authorization and its source, power, per-phase voltage,
+  current and frequency, session, last-session and lifetime energy, battery
+  state of charge (DC), inner and ambient temperature.
+
+`async_update()` reads each sub-system on its own and returns an
+`UpdateReport` naming what refreshed and what failed, so one silent connector
+does not blank the rest. A link that answers nothing raises
+`IontConnectionError`.
+
+## Commands
+
+- `async_authorize(number, boost=False)` / `async_deauthorize(number)`: start
+  or stop charging on a connector by its 1-based number. `boost=True` charges at
+  full available current even under the eco strategy.
+- `async_authorize_by_id(connector_id)` / `async_deauthorize_by_id(connector_id)`:
+  the same, addressing the connector by its OCPP connector ID.
+- `async_set_external_power_limit(watts)` / `async_clear_external_power_limit()`:
+  cap the charging power from outside, for example from a home energy manager.
+
+A command that the charger does not process in time, or reports a result
+other than success for, raises `IontCommandError`.
+
+## Develop
+
+```bash
+uv sync --extra tmodbus
+uv run pytest
+uv run mypy
+uv run ruff check
+```
+
+## License
+
+MIT

pyiont-0.1.0/pyproject.toml

@@ -0,0 +1,99 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyiont"
+version = "0.1.0"
+description = "Asynchronous Python client for IONT EV chargers over Modbus TCP."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "IONT", email = "info@iont.tech" }]
+requires-python = ">=3.13"
+keywords = [
+  "async",
+  "ev-charger",
+  "evse",
+  "home-assistant",
+  "iont",
+  "modbus",
+  "wallbox",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: AsyncIO",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Home Automation",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = ["modbus-connection>=4.8.1"]
+
+[project.optional-dependencies]
+tmodbus = ["modbus-connection[tmodbus]>=4.8.1"]
+pymodbus = ["modbus-connection[pymodbus]>=4.8.1"]
+
+[project.urls]
+Homepage = "https://github.com/IONTtech/pyiont"
+Repository = "https://github.com/IONTtech/pyiont"
+Documentation = "https://github.com/IONTtech/pyiont"
+"Bug Tracker" = "https://github.com/IONTtech/pyiont/issues"
+Changelog = "https://github.com/IONTtech/pyiont/releases"
+
+[dependency-groups]
+dev = [
+  "mypy>=1.14",
+  "pytest>=8.3",
+  "pytest-asyncio>=0.25",
+  "pytest-cov>=6.0",
+  "ruff>=0.9",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyiont"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/pyiont", "tests", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+addopts = "--strict-markers --strict-config"
+testpaths = ["tests"]
+xfail_strict = true
+
+[tool.coverage.run]
+source = ["pyiont"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 100
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+files = ["src/pyiont"]
+
+[tool.ruff]
+target-version = "py313"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+  "ANN401",  # Any is needed for the generic write validators
+  "COM812",  # handled by the formatter
+  "D203",    # conflicts with D211
+  "D213",    # conflicts with D212
+  "CPY001",  # no per-file copyright headers
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D", "PLR2004", "S101", "SLF001"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"

pyiont-0.1.0/src/pyiont/__init__.py

@@ -0,0 +1,48 @@
+"""Asynchronous Python client for IONT EV chargers over Modbus TCP."""
+
+from .charger import (
+    SUBSYSTEM_DEVICE,
+    SUBSYSTEM_SETTINGS,
+    IontCharger,
+    UpdateReport,
+    connector_subsystem,
+)
+from .components import CommandResult, Connector, Device, Settings
+from .const import (
+    DEFAULT_PORT,
+    EXTERNAL_POWER_LIMIT_MAX,
+    MAX_CONNECTORS,
+    AuthorizedBy,
+    ChargingState,
+    ChargingStrategy,
+    ConnectionState,
+    CurrentFlow,
+    DeviceStatus,
+    VehicleState,
+)
+from .exceptions import IontCommandError, IontConnectionError, IontError
+
+__all__ = [
+    "DEFAULT_PORT",
+    "EXTERNAL_POWER_LIMIT_MAX",
+    "MAX_CONNECTORS",
+    "SUBSYSTEM_DEVICE",
+    "SUBSYSTEM_SETTINGS",
+    "AuthorizedBy",
+    "ChargingState",
+    "ChargingStrategy",
+    "CommandResult",
+    "ConnectionState",
+    "Connector",
+    "CurrentFlow",
+    "Device",
+    "DeviceStatus",
+    "IontCharger",
+    "IontCommandError",
+    "IontConnectionError",
+    "IontError",
+    "Settings",
+    "UpdateReport",
+    "VehicleState",
+    "connector_subsystem",
+]

pyiont-0.1.0/src/pyiont/charger.py

@@ -0,0 +1,260 @@
+"""The IONT charger device object."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from modbus_connection import ModbusConnectionError, ModbusError, ModbusTimeoutError
+
+from .components import CommandResult, Connector, Device, Settings
+from .const import (
+    AUTHORIZE_BOOST_BY_CONNECTOR_ID_ADDRESS,
+    AUTHORIZE_BY_CONNECTOR_ID_ADDRESS,
+    COMMAND_POLL_INTERVAL,
+    COMMAND_RESULT_OK,
+    COMMAND_TIMEOUT,
+    CONNECTOR_AUTHORIZE_OFFSET,
+    CONNECTOR_BASE,
+    CONNECTOR_DEAUTHORIZE_OFFSET,
+    CONNECTOR_STRIDE,
+    DEAUTHORIZE_BY_CONNECTOR_ID_ADDRESS,
+    EXTERNAL_POWER_LIMIT_MAX,
+    MAX_CONNECTORS,
+)
+from .exceptions import IontCommandError, IontConnectionError, IontError
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from modbus_connection import ModbusUnit
+    from modbus_connection.model import Component
+
+SUBSYSTEM_DEVICE = "device"
+SUBSYSTEM_SETTINGS = "settings"
+
+
+def connector_subsystem(number: int) -> str:
+    """Return the sub-system name of the connector with a 1-based number."""
+    return f"connector_{number}"
+
+
+@dataclass(frozen=True)
+class UpdateReport:
+    """What one poll refreshed, named by sub-system.
+
+    A sub-system in ``failed`` kept the values it had. A poll that refreshed
+    nothing raises :class:`IontConnectionError` instead of reporting total
+    silence here.
+    """
+
+    updated: set[str]
+    failed: dict[str, IontError]
+
+    @property
+    def complete(self) -> bool:
+        """Whether every sub-system refreshed."""
+        return not self.failed
+
+
+class IontCharger:
+    """An IONT charger reached through a ``ModbusUnit``.
+
+    The caller owns the connection and hands over a unit. Prefer
+    :meth:`async_probe`, which asks the charger how many connectors it has.
+    The constructor serves a caller that already knows.
+    """
+
+    def __init__(self, unit: ModbusUnit, *, connectors: int) -> None:
+        """Set up the components for a charger with ``connectors`` connectors."""
+        if not 1 <= connectors <= MAX_CONNECTORS:
+            msg = f"connectors must be between 1 and {MAX_CONNECTORS}, got {connectors}"
+            raise IontError(msg)
+
+        self._unit = unit
+        self._command_lock = asyncio.Lock()
+        self._result = CommandResult(unit)
+
+        self.device = Device(unit)
+        self.settings = Settings(unit)
+        self.connectors: list[Connector] = [
+            Connector(unit, base_offset=CONNECTOR_BASE + CONNECTOR_STRIDE * index)
+            for index in range(connectors)
+        ]
+
+    @classmethod
+    async def async_probe(cls, unit: ModbusUnit) -> IontCharger:
+        """Read the charger's layout on ``unit`` and return a ready instance.
+
+        Raises :class:`IontConnectionError` when the device does not answer,
+        and :class:`IontError` when what answers does not present as an IONT
+        charger.
+        """
+        device = Device(unit)
+        try:
+            await device.async_update(notify=False)
+        except ModbusError as err:
+            raise IontConnectionError(str(err)) from err
+
+        count = device.connector_count
+        if count is None or not 1 <= count <= MAX_CONNECTORS:
+            msg = "The device does not answer as an IONT charger"
+            raise IontError(msg)
+
+        charger = cls(unit, connectors=count)
+        # Hand over what was just read rather than reading it again.
+        charger.device = device
+        return charger
+
+    @property
+    def connector_count(self) -> int:
+        """How many connectors this charger serves."""
+        return len(self.connectors)
+
+    @property
+    def components(self) -> list[Component]:
+        """Every polled component, in read order."""
+        return [self.device, self.settings, *self.connectors]
+
+    def _targets(self) -> Iterator[tuple[str, Component]]:
+        """Yield the polled sub-systems by name."""
+        yield SUBSYSTEM_DEVICE, self.device
+        yield SUBSYSTEM_SETTINGS, self.settings
+        for number, connector in enumerate(self.connectors, 1):
+            yield connector_subsystem(number), connector
+
+    async def async_update(self) -> UpdateReport:
+        """Refresh every sub-system, each on its own, and report what answered."""
+        updated: set[str] = set()
+        failed: dict[str, IontError] = {}
+
+        for name, component in self._targets():
+            try:
+                await component.async_update()
+            except ModbusConnectionError as err:
+                raise IontConnectionError(str(err)) from err
+            except ModbusTimeoutError as err:
+                # Nothing has answered yet: the rest would only pay a timeout each.
+                if not updated and not failed:
+                    raise IontConnectionError(str(err)) from err
+                failed[name] = IontConnectionError(str(err))
+            except ModbusError as err:
+                failed[name] = IontConnectionError(str(err))
+            else:
+                updated.add(name)
+
+        if failed and not updated:
+            msg = "No sub-system answered: " + "; ".join(map(str, failed.values()))
+            raise IontConnectionError(msg)
+
+        return UpdateReport(updated=updated, failed=failed)
+
+    async def async_read_raw(self) -> dict[str, dict[int, int | bool]]:
+        """Every register this charger reads, undecoded, for diagnostics."""
+        raw: dict[str, dict[int, int | bool]] = {}
+        for _name, component in self._targets():
+            try:
+                read = await component.async_read_raw(notify=False)
+            except ModbusError as err:
+                raise IontConnectionError(str(err)) from err
+            for space, values in read.items():
+                raw.setdefault(space, {}).update(values)
+        return raw
+
+    # -- commands ------------------------------------------------------------
+
+    def _connector(self, number: int) -> Connector:
+        """Return the connector with a 1-based number."""
+        if not 1 <= number <= len(self.connectors):
+            msg = f"connector {number} does not exist (1 to {len(self.connectors)})"
+            raise IontError(msg)
+        return self.connectors[number - 1]
+
+    def _connector_id(self, number: int) -> int:
+        """Return the OCPP connector ID the charger knows a connector by."""
+        connector_id = self._connector(number).connector_id
+        if not connector_id:
+            msg = f"connector {number} has no connector ID, so it cannot be addressed"
+            raise IontError(msg)
+        return connector_id
+
+    async def async_authorize(self, number: int, *, boost: bool = False) -> None:
+        """Authorize charging on a connector, by its 1-based number.
+
+        With ``boost`` the connector charges at full available current even
+        under the eco strategy, instead of waiting for surplus power. That
+        command addresses the connector by its OCPP connector ID, so it needs
+        one to be set.
+        """
+        if boost:
+            await self._async_command(
+                AUTHORIZE_BOOST_BY_CONNECTOR_ID_ADDRESS, self._connector_id(number)
+            )
+            return
+        connector = self._connector(number)
+        await self._async_command(
+            connector.base_address + CONNECTOR_AUTHORIZE_OFFSET, 1
+        )
+
+    async def async_deauthorize(self, number: int) -> None:
+        """Withdraw the authorization of a connector, by its 1-based number."""
+        connector = self._connector(number)
+        await self._async_command(
+            connector.base_address + CONNECTOR_DEAUTHORIZE_OFFSET, 1
+        )
+
+    async def async_authorize_by_id(self, connector_id: int) -> None:
+        """Authorize charging on the connector with an OCPP connector ID."""
+        await self._async_command(AUTHORIZE_BY_CONNECTOR_ID_ADDRESS, connector_id)
+
+    async def async_deauthorize_by_id(self, connector_id: int) -> None:
+        """Withdraw the authorization of the connector with an OCPP connector ID."""
+        await self._async_command(DEAUTHORIZE_BY_CONNECTOR_ID_ADDRESS, connector_id)
+
+    async def async_set_external_power_limit(self, watts: int) -> None:
+        """Cap the charging power from outside, for example from a home energy manager.
+
+        Writing 0 stops charging; writing :data:`EXTERNAL_POWER_LIMIT_MAX`
+        lifts the cap. The charger reads the cap back as the effective limit.
+        """
+        try:
+            await self.settings.write("external_power_limit", watts)
+        except ModbusError as err:
+            raise IontConnectionError(str(err)) from err
+
+    async def async_clear_external_power_limit(self) -> None:
+        """Lift the external charging power cap."""
+        await self.async_set_external_power_limit(EXTERNAL_POWER_LIMIT_MAX)
+
+    async def _async_command(self, address: int, value: int) -> None:
+        """Write a command trigger and wait for the charger to carry it out.
+
+        The charger processes triggers on its own cycle: it carries the command
+        out, records the result and resets the trigger to 0. Commands are
+        serialized because the result register is shared between them.
+        """
+        async with self._command_lock:
+            try:
+                await self._unit.write_register(address, value)
+                await self._async_wait_for_trigger(address)
+                await self._result.async_update(notify=False)
+            except ModbusError as err:
+                raise IontConnectionError(str(err)) from err
+
+        if (code := self._result.code) != COMMAND_RESULT_OK:
+            msg = f"The charger rejected the command (result code {code})"
+            raise IontCommandError(msg, code=code)
+
+    async def _async_wait_for_trigger(self, address: int) -> None:
+        """Poll a trigger register until the charger resets it."""
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + COMMAND_TIMEOUT
+        while True:
+            await asyncio.sleep(COMMAND_POLL_INTERVAL)
+            (pending,) = await self._unit.read_holding_registers(address, 1)
+            if pending == 0:
+                return
+            if loop.time() >= deadline:
+                msg = "The charger did not process the command in time"
+                raise IontCommandError(msg)