pyiont 0.1.0__py3-none-any.whl

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/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)

pyiont/components.py

@@ -0,0 +1,194 @@
+"""Register components of an IONT charger, modelled on ``modbus-connection``.
+
+Each :class:`~modbus_connection.model.Component` maps one block of the
+charger's register map to typed attributes. Multi-register values are
+big-endian in both byte and word order, which is the library default.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from modbus_connection.model import (
+    Component,
+    boolean,
+    enum,
+    float32,
+    gauge,
+    int32,
+    integer,
+)
+
+from .const import (
+    COMMAND_RESULT_ADDRESS,
+    DEVICE_BASE,
+    EXTERNAL_POWER_LIMIT_ADDRESS,
+    EXTERNAL_POWER_LIMIT_MAX,
+    AuthorizedBy,
+    ChargingState,
+    ChargingStrategy,
+    ConnectionState,
+    CurrentFlow,
+    DeviceStatus,
+    VehicleState,
+)
+from .exceptions import IontError
+
+if TYPE_CHECKING:
+    from modbus_connection import ModbusUnit
+
+
+def _power_limit(value: Any) -> int:
+    """Vet an external power limit before it is written."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        msg = f"power limit must be a number, got {value!r}"
+        raise IontError(msg)
+    watts = int(value)
+    if not 0 <= watts <= EXTERNAL_POWER_LIMIT_MAX:
+        msg = f"power limit {watts} W is out of range (0 to {EXTERNAL_POWER_LIMIT_MAX})"
+        raise IontError(msg)
+    return watts
+
+
+class Device(Component):
+    """The device-wide block: configuration, limits and overall status."""
+
+    register_space = "input"
+    register_ranges = ((DEVICE_BASE, DEVICE_BASE + 0x00B),)
+
+    main_breaker_current = integer(DEVICE_BASE + 0x000, signed=False, unit="A")
+    """Current limit of the main circuit breaker, as configured."""
+
+    charger_breaker_current = integer(DEVICE_BASE + 0x001, signed=False, unit="A")
+    """Current limit of the charger-side circuit breaker."""
+
+    phase_count = integer(DEVICE_BASE + 0x002, signed=False)
+    """Number of grid phases the charger is wired for (1 or 3)."""
+
+    free_charging = boolean(DEVICE_BASE + 0x003)
+    """Whether charging needs no authorization."""
+
+    power_limit_user = integer(DEVICE_BASE + 0x004, signed=False, unit="W")
+    """User-configured charging power ceiling."""
+
+    available_power = integer(DEVICE_BASE + 0x005, signed=False, unit="W")
+    """Charging power available right now, after every limiter."""
+
+    charging_strategy = enum(DEVICE_BASE + 0x006, ChargingStrategy)
+    """How available power is distributed across the connectors."""
+
+    status = enum(DEVICE_BASE + 0x007, DeviceStatus)
+    """Overall status of the charger."""
+
+    uptime = int32(DEVICE_BASE + 0x008, unit="s")
+    """Seconds since the charger started."""
+
+    connector_count = int32(DEVICE_BASE + 0x00A)
+    """Number of charging connectors the charger serves."""
+
+
+class Settings(Component):
+    """The writable device settings, served as holding registers."""
+
+    register_space = "holding"
+    register_ranges = ((EXTERNAL_POWER_LIMIT_ADDRESS, EXTERNAL_POWER_LIMIT_ADDRESS),)
+
+    external_power_limit = integer(
+        EXTERNAL_POWER_LIMIT_ADDRESS, signed=False, writable=_power_limit, unit="W"
+    )
+    """External charging power cap (W); reads back as the effective limit."""
+
+
+class CommandResult(Component):
+    """The result of the most recent command, as an input register."""
+
+    register_space = "input"
+    register_ranges = ((COMMAND_RESULT_ADDRESS, COMMAND_RESULT_ADDRESS + 1),)
+
+    code = int32(COMMAND_RESULT_ADDRESS)
+    """Result code of the most recent command; 1 means it was carried out."""
+
+
+class Connector(Component):
+    """One charging connector's state and measurements.
+
+    Addresses are offsets within the connector block. Build one with
+    ``base_offset`` set to the block's start on the device.
+    """
+
+    register_space = "input"
+    register_ranges = ((0x00, 0x2B),)
+
+    def __init__(self, unit: ModbusUnit, *, base_offset: int) -> None:
+        """Bind the connector block that starts at ``base_offset`` on the device."""
+        super().__init__(unit, base_offset=base_offset)
+        self.base_address = base_offset
+        """First address of this connector's block on the device."""
+
+    identifier = int32(0x00)
+    """32-bit identifier of the connector record on the charger."""
+
+    connector_id = integer(0x02, signed=False)
+    """1-based connector ID as used by OCPP; 0 when none is set."""
+
+    current_flow = enum(0x03, CurrentFlow)
+    """Whether this connector charges with AC or DC."""
+
+    connection_state = enum(0x04, ConnectionState)
+    """Communication state between the charger and this connector's controller."""
+
+    vehicle_state = enum(0x05, VehicleState)
+    """Physical state of the vehicle and cable."""
+
+    charging_state = enum(0x06, ChargingState)
+    """What the connector is doing with the vehicle."""
+
+    charging = boolean(0x07)
+    """True while energy is flowing."""
+
+    authorized = boolean(0x08)
+    """True while the connector holds an authorization."""
+
+    authorized_by = enum(0x09, AuthorizedBy)
+    """What granted the current authorization."""
+
+    power_limit = float32(0x0A, unit="W")
+    """Configured charging power ceiling of this connector."""
+
+    power = int32(0x0C, unit="W")
+    """Active power, summed over the phases."""
+
+    voltage_l1 = float32(0x0E, unit="V")
+    voltage_l2 = float32(0x10, unit="V")
+    voltage_l3 = float32(0x12, unit="V")
+
+    current_l1 = float32(0x14, unit="A")
+    current_l2 = float32(0x16, unit="A")
+    current_l3 = float32(0x18, unit="A")
+
+    frequency_l1 = float32(0x1A, unit="Hz")
+    frequency_l2 = float32(0x1C, unit="Hz")
+    frequency_l3 = float32(0x1E, unit="Hz")
+
+    session_energy = float32(0x20, unit="Wh")
+    """Energy delivered in the current session."""
+
+    last_session_energy = float32(0x22, unit="Wh")
+    """Energy delivered in the most recent finished session."""
+
+    total_energy = float32(0x24, unit="Wh")
+    """Lifetime reading of the connector's energy meter."""
+
+    battery_soc = gauge(0x26, 0.1, signed=False, unit="%")
+    """Vehicle battery state of charge; DC connectors only, AC reports 0."""
+
+    temperature_inner = float32(0x28, unit="°C")
+    """Temperature inside the connector's electronics; 0 where not measured."""
+
+    temperature_ambient = float32(0x2A, unit="°C")
+    """Ambient temperature at the connector; 0 where not measured."""
+
+    @property
+    def is_dc(self) -> bool:
+        """Whether this connector charges with direct current."""
+        return self.current_flow is CurrentFlow.DC

pyiont/const.py

@@ -0,0 +1,137 @@
+"""Constants for the IONT charger Modbus TCP register map."""
+
+from __future__ import annotations
+
+from enum import IntEnum
+from typing import Final
+
+DEFAULT_PORT: Final = 502
+"""The TCP port an IONT charger listens on for Modbus requests."""
+
+# -- Register layout -----------------------------------------------------------
+# The map has a device-wide block and one block per charging connector. Device
+# state is served as input registers (FC04); the few writable settings and
+# command triggers are holding registers (FC03 / FC06).
+
+DEVICE_BASE: Final = 0x1000
+"""First address of the device-wide block."""
+
+CONNECTOR_BASE: Final = 0x2000
+"""First address of the first connector's block."""
+
+CONNECTOR_STRIDE: Final = 0x80
+"""Registers between the start of one connector block and the next."""
+
+ADDRESS_SPACE_SIZE: Final = 0x7000
+"""The highest address the charger serves, plus one."""
+
+MAX_CONNECTORS: Final = (ADDRESS_SPACE_SIZE - CONNECTOR_BASE) // CONNECTOR_STRIDE
+"""How many connector blocks fit in the address space."""
+
+COMMAND_RESULT_ADDRESS: Final = DEVICE_BASE + 0x100
+"""Input register (int32) holding the result of the most recent command."""
+
+COMMAND_RESULT_OK: Final = 1
+"""The result code the charger reports for a command it carried out."""
+
+# Holding registers of the device block.
+EXTERNAL_POWER_LIMIT_ADDRESS: Final = DEVICE_BASE + 0x002
+AUTHORIZE_BY_CONNECTOR_ID_ADDRESS: Final = DEVICE_BASE + 0x010
+DEAUTHORIZE_BY_CONNECTOR_ID_ADDRESS: Final = DEVICE_BASE + 0x011
+AUTHORIZE_BOOST_BY_CONNECTOR_ID_ADDRESS: Final = DEVICE_BASE + 0x012
+
+# Holding registers of a connector block, as offsets from the block start.
+CONNECTOR_AUTHORIZE_OFFSET: Final = 0x01
+CONNECTOR_DEAUTHORIZE_OFFSET: Final = 0x02
+
+EXTERNAL_POWER_LIMIT_MAX: Final = 0xFFFF
+"""The largest external power limit (W) the register holds; writing it lifts the cap."""
+
+# -- Command handling ----------------------------------------------------------
+# A command is a write to a trigger register. The charger picks it up on its
+# own cycle, carries it out, records the result and resets the trigger to 0.
+
+COMMAND_TIMEOUT: Final = 3.0
+"""Seconds to wait for the charger to reset a command trigger."""
+
+COMMAND_POLL_INTERVAL: Final = 0.1
+"""Seconds between reads of a pending command trigger."""
+
+
+# -- Enumerations --------------------------------------------------------------
+# The numeric codes the charger reports. Member names double as the
+# machine-readable state names consumers show or translate.
+
+
+class DeviceStatus(IntEnum):
+    """Overall status of the charger."""
+
+    UNKNOWN = 0
+    INIT = 1
+    OPERATIONAL = 2
+    OUT_OF_ORDER = 3
+    MAINTENANCE = 4
+    AUTH_NOT_POSSIBLE = 5
+    DEACTIVATED = 6
+
+
+class ChargingStrategy(IntEnum):
+    """How available power is distributed across the connectors."""
+
+    UNKNOWN = 0
+    NORMAL = 1
+    ECO = 2
+    BOOST = 3
+
+
+class CurrentFlow(IntEnum):
+    """Whether a connector charges with alternating or direct current."""
+
+    UNKNOWN = 0
+    AC = 1
+    DC = 2
+
+
+class ConnectionState(IntEnum):
+    """Communication state between the charger and a connector's controller."""
+
+    UNKNOWN = 0
+    OFFLINE = 1
+    ONLINE = 2
+
+
+class VehicleState(IntEnum):
+    """Physical state of the vehicle and cable at a connector."""
+
+    UNKNOWN = 0
+    NOT_CONNECTED = 1
+    CONNECTED = 2
+    WANTS_TO_CHARGE = 3
+    NEEDS_TO_VENTILATE = 4
+    ERROR = 5
+
+
+class ChargingState(IntEnum):
+    """What a connector is doing with the vehicle."""
+
+    UNKNOWN = 0
+    NOT_CHARGING = 1
+    CHARGING_1F = 2
+    CHARGING_3F = 3
+    CHARGING_DC = 4
+    PAUSED = 5
+    CHARGING_DONE = 6
+
+
+class AuthorizedBy(IntEnum):
+    """What authorized the current charging session."""
+
+    UNKNOWN = 0
+    NOT_CHARGING = 1
+    RFID = 2
+    TIMER = 3
+    REMOTE = 4
+    AUTO = 5
+    MODBUS = 6
+    MQTT = 7
+    OCPP = 8

pyiont/exceptions.py

@@ -0,0 +1,26 @@
+"""Exceptions raised by the IONT charger client."""
+
+
+class IontError(Exception):
+    """Base exception for the IONT charger client."""
+
+
+class IontConnectionError(IontError):
+    """Communicating with the charger over Modbus failed.
+
+    Wraps the backend-neutral error from ``modbus-connection``: a dead link, a
+    timeout, or a request the charger refused.
+    """
+
+
+class IontCommandError(IontError):
+    """The charger did not carry out a command.
+
+    Raised when a command trigger is not processed in time, or when the charger
+    reports a result code other than success for it.
+    """
+
+    def __init__(self, message: str, *, code: int | None = None) -> None:
+        """Initialize the error with the result code the charger reported, if any."""
+        super().__init__(message)
+        self.code = code

pyiont-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+pyiont/__init__.py,sha256=8j-cvxCKTT4GciX3L3R4oS4VqE8Nb-jUPNcci9-xHYQ,1055
+pyiont/charger.py,sha256=lMXT3ig7XiDrOw2BeZc_PbqjyKzyem4XvtiYiohvM5Y,10276
+pyiont/components.py,sha256=mTJy5qgxWY0tZTiNy2BviNVup6V4zexMV0F-agMMtO8,6469
+pyiont/const.py,sha256=K3zFgJajuIyFXqvnx3OJQ0zMJ_oR9DjvZ7vRO7FqPQc,3822
+pyiont/exceptions.py,sha256=hnEyk4C3YsCYwtL1uAyyH3Y2oYEIVoxVFQApxIP1zV4,816
+pyiont/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyiont-0.1.0.dist-info/METADATA,sha256=UTfh_JQvHAAKDUyOA_BOaf7oYsuRMXmJWd3t_NAJDRQ,4719
+pyiont-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pyiont-0.1.0.dist-info/licenses/LICENSE,sha256=mDPsm5n-_cg-o0AepANEdyvPK26EOKd5lFtL6x72GQY,1061
+pyiont-0.1.0.dist-info/RECORD,,

pyiont-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pyiont-0.1.0.dist-info/licenses/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.