scietex.hal.vfd 2.0.0__tar.gz

scietex_hal_vfd-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anton Bondarenko
+
+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.

scietex_hal_vfd-2.0.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: scietex.hal.vfd
+Version: 2.0.0
+Summary: Scietex VFD HAL package
+Author-email: Anton Bondarenko <bond.anton@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Anton Bondarenko
+        
+        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.
+Project-URL: Homepage, https://github.com/bond-anton/scietex.hal.vfd
+Project-URL: Bug Tracker, https://github.com/bond-anton/scietex.hal.vfd/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: msgspec[yaml]~=0.20.0
+Requires-Dist: scietex.hal.serial<3.0.0,>=2.4.0
+Requires-Dist: pymodbus~=3.15
+Provides-Extra: dev
+Requires-Dist: tox>=4.46.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: pytest-xdist; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Requires-Dist: ty; extra == "lint"
+Dynamic: license-file
+
+# scietex.hal.vfd
+
+The `scietex.hal.vfd` package is a Python library for interfacing with variable
+frequency drives (VFD). It defines a transport-agnostic driver contract
+(`VFDProtocol`) plus the data structures and capability model shared by every
+driver, and ships concrete implementations for three drive families.
+
+A driver reaches a drive over one of two transports:
+
+- **Direct RS485** — the driver owns the serial port and speaks Modbus RTU to
+  the drive itself (`scietex.hal.vfd.base.rs485.VFD`).
+- **Scietex Modbus gateway** — the gateway owns the RS485 bus, and the driver
+  speaks Modbus/TCP to a gateway device entry that routes to the drive by unit
+  id (`scietex.hal.vfd.intek.spe_b.client.IntekSPEBModbusVFD`).
+
+## Features
+
+- `VFDProtocol`, a runtime-checkable contract: connect, disconnect, read
+  parameters, read state, read and reset faults, start, stop and set the
+  frequency setpoint.
+- `VFDCapabilities`, which advertises optional control surface (direction, jog,
+  freewheel stop, fault reset, frequency setpoint) so a caller can reject an
+  unsupported command before dispatching it.
+- `VFDParameters`, which reports frequency in both Hz and percent of the
+  configured maximum, plus output current, voltage and power, and the optional
+  DC bus voltage and temperatures a drive exposes. An optional field is `None`
+  when the drive does not report it, which is distinct from a reported `0.0`.
+- Implemented drive models, each with both transports:
+  - `Intek SPE-B` — direct RS485 (`SPEvB`) and gateway (`IntekSPEBModbusVFD`).
+  - `Vesper E5-8200` — direct RS485 (`VesperE58200`) and gateway
+    (`VesperE58200ModbusVFD`).
+  - `Vesper E4-8400` / `E4-P8402` — direct RS485 (`VesperE48400`) and gateway
+    (`VesperE48400ModbusVFD`).
+- Driver descriptors for the gateway (`scietex.modbus.drivers` entry-point
+  group) and driver classes for a service (`scietex.hal.vfd.drivers` group).
+
+### What each drive reports
+
+| Field | Intek SPE-B | Vesper E5-8200 | Vesper E4-8400 |
+| --- | --- | --- | --- |
+| `frequency_hz` | yes | yes | yes |
+| `frequency_percent` | yes | yes | yes |
+| `output_current` | yes | yes | yes |
+| `output_voltage` | yes | yes | yes |
+| `output_power` | yes | no (`0.0`) | no (`0.0`) |
+| `dc_bus_voltage` | yes | yes | yes |
+| `heatsink_temperature_c` | no (`None`) | no (`None`) | yes |
+| `motor_temperature_c` | no (`None`) | no (`None`) | no (`None`) |
+
+Only the E4-8400 exposes a live temperature reading (`004Dh`, U1-46). The other
+two report overheat only as a fault code, and a fault is not a temperature.
+
+## Installation
+
+Install the package via pip (assuming it's published to PyPI):
+
+```bash
+pip install scietex.hal.vfd
+```
+
+Alternatively, clone the repository and install locally:
+
+```bash
+git clone https://github.com/bond-anton/scietex.hal.vfd.git
+cd scietex.hal.vfd
+pip install .
+```
+
+## Requirements
+
+- Python 3.10 or higher.
+- `scietex.hal.serial` 2.4 or newer (RS485 transport and Modbus gateway
+  descriptors).
+- `pymodbus` 3.15 or newer (Modbus/TCP client for the gateway transport).
+
+## Usage
+
+Every driver implements `VFDProtocol`: `connect`, `close`, `read_data`,
+`read_parameters`, `read_state`, `read_error_code`, `clear_error`, `start`,
+`stop` and `set_frequency`. Check `driver.capabilities` before issuing an
+optional command.
+
+Direct RS485 with the Intek SPE-B VFD:
+
+```python
+import asyncio
+
+from scietex.hal.serial import ModbusSerialConnectionConfig
+from scietex.hal.vfd.intek import SPEvB
+
+
+async def main(serial_conf: ModbusSerialConnectionConfig):
+    """Main function."""
+    vfd = SPEvB(serial_conf, address=1, label="Intek VFD")
+    data = await vfd.read_data()
+    print(data)
+
+
+if __name__ == "__main__":
+    serial_configuration = ModbusSerialConnectionConfig(
+        port="/dev/serial0", baudrate=19200
+    )
+    asyncio.run(main(serial_configuration))
+```
+
+The same drive behind the Scietex Modbus gateway:
+
+```python
+import asyncio
+
+from scietex.hal.vfd.intek import IntekSPEBModbusVFD
+
+
+async def main():
+    """Main function."""
+    vfd = IntekSPEBModbusVFD("gateway.local", port=502, unit_id=1)
+    await vfd.connect()
+    try:
+        print(await vfd.read_data())
+        print(await vfd.read_error_code())
+    finally:
+        await vfd.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+A Vesper drive behind the gateway works the same way:
+
+```python
+from scietex.hal.vfd.vesper import VesperE48400ModbusVFD
+
+vfd = VesperE48400ModbusVFD("gateway.local", port=502, unit_id=1)
+```
+
+`set_frequency` takes Hz, not percent: the caller works in engineering units and
+each driver converts with its own maximum-frequency parameter. The E5-8200's
+communication manual names no maximum-frequency parameter, so its driver takes
+`max_frequency_hz` from the constructor (default `50.0`, the factory base
+frequency); a caller whose drive runs a different maximum must pass it, or
+`frequency_percent` will be wrong.
+
+A drive that has never been configured for the gateway answers neither
+transport. See the per-family references for the register maps, the fault tables
+and the settings the gateway requires:
+
+- [`intek/docs/protocol.md`](src/scietex/hal/vfd/intek/docs/protocol.md) —
+  Intek SPE-B (`Pd.01`/`Pd.05`/`Pd.02`).
+- [`vesper/docs/README.md`](src/scietex/hal/vfd/vesper/docs/README.md) — Vesper
+  E5-8200 and E4-8400, plus the transport facts both manuals share.
+
+## Contributing
+
+Contributions are welcome! To contribute:
+
+1. Fork the repository.
+2. Create a feature branch (`git checkout -b feature/YourFeature`).
+3. Commit your changes (`git commit -m "Add your message"`).
+4. Push to the branch (`git push origin feature/YourFeature`).
+5. Open a Pull Request.
+
+Run the checks before opening a pull request:
+
+```bash
+tox -e format,lint,type,test
+```
+
+`format` and `lint` run `ruff`, `type` runs `ty`, and `test` runs `pytest` across
+Python 3.10, 3.12 and 3.14.
+
+## License
+
+This project is licensed under the **MIT License** - see the LICENSE file for details.

scietex_hal_vfd-2.0.0/README.md

@@ -0,0 +1,174 @@
+# scietex.hal.vfd
+
+The `scietex.hal.vfd` package is a Python library for interfacing with variable
+frequency drives (VFD). It defines a transport-agnostic driver contract
+(`VFDProtocol`) plus the data structures and capability model shared by every
+driver, and ships concrete implementations for three drive families.
+
+A driver reaches a drive over one of two transports:
+
+- **Direct RS485** — the driver owns the serial port and speaks Modbus RTU to
+  the drive itself (`scietex.hal.vfd.base.rs485.VFD`).
+- **Scietex Modbus gateway** — the gateway owns the RS485 bus, and the driver
+  speaks Modbus/TCP to a gateway device entry that routes to the drive by unit
+  id (`scietex.hal.vfd.intek.spe_b.client.IntekSPEBModbusVFD`).
+
+## Features
+
+- `VFDProtocol`, a runtime-checkable contract: connect, disconnect, read
+  parameters, read state, read and reset faults, start, stop and set the
+  frequency setpoint.
+- `VFDCapabilities`, which advertises optional control surface (direction, jog,
+  freewheel stop, fault reset, frequency setpoint) so a caller can reject an
+  unsupported command before dispatching it.
+- `VFDParameters`, which reports frequency in both Hz and percent of the
+  configured maximum, plus output current, voltage and power, and the optional
+  DC bus voltage and temperatures a drive exposes. An optional field is `None`
+  when the drive does not report it, which is distinct from a reported `0.0`.
+- Implemented drive models, each with both transports:
+  - `Intek SPE-B` — direct RS485 (`SPEvB`) and gateway (`IntekSPEBModbusVFD`).
+  - `Vesper E5-8200` — direct RS485 (`VesperE58200`) and gateway
+    (`VesperE58200ModbusVFD`).
+  - `Vesper E4-8400` / `E4-P8402` — direct RS485 (`VesperE48400`) and gateway
+    (`VesperE48400ModbusVFD`).
+- Driver descriptors for the gateway (`scietex.modbus.drivers` entry-point
+  group) and driver classes for a service (`scietex.hal.vfd.drivers` group).
+
+### What each drive reports
+
+| Field | Intek SPE-B | Vesper E5-8200 | Vesper E4-8400 |
+| --- | --- | --- | --- |
+| `frequency_hz` | yes | yes | yes |
+| `frequency_percent` | yes | yes | yes |
+| `output_current` | yes | yes | yes |
+| `output_voltage` | yes | yes | yes |
+| `output_power` | yes | no (`0.0`) | no (`0.0`) |
+| `dc_bus_voltage` | yes | yes | yes |
+| `heatsink_temperature_c` | no (`None`) | no (`None`) | yes |
+| `motor_temperature_c` | no (`None`) | no (`None`) | no (`None`) |
+
+Only the E4-8400 exposes a live temperature reading (`004Dh`, U1-46). The other
+two report overheat only as a fault code, and a fault is not a temperature.
+
+## Installation
+
+Install the package via pip (assuming it's published to PyPI):
+
+```bash
+pip install scietex.hal.vfd
+```
+
+Alternatively, clone the repository and install locally:
+
+```bash
+git clone https://github.com/bond-anton/scietex.hal.vfd.git
+cd scietex.hal.vfd
+pip install .
+```
+
+## Requirements
+
+- Python 3.10 or higher.
+- `scietex.hal.serial` 2.4 or newer (RS485 transport and Modbus gateway
+  descriptors).
+- `pymodbus` 3.15 or newer (Modbus/TCP client for the gateway transport).
+
+## Usage
+
+Every driver implements `VFDProtocol`: `connect`, `close`, `read_data`,
+`read_parameters`, `read_state`, `read_error_code`, `clear_error`, `start`,
+`stop` and `set_frequency`. Check `driver.capabilities` before issuing an
+optional command.
+
+Direct RS485 with the Intek SPE-B VFD:
+
+```python
+import asyncio
+
+from scietex.hal.serial import ModbusSerialConnectionConfig
+from scietex.hal.vfd.intek import SPEvB
+
+
+async def main(serial_conf: ModbusSerialConnectionConfig):
+    """Main function."""
+    vfd = SPEvB(serial_conf, address=1, label="Intek VFD")
+    data = await vfd.read_data()
+    print(data)
+
+
+if __name__ == "__main__":
+    serial_configuration = ModbusSerialConnectionConfig(
+        port="/dev/serial0", baudrate=19200
+    )
+    asyncio.run(main(serial_configuration))
+```
+
+The same drive behind the Scietex Modbus gateway:
+
+```python
+import asyncio
+
+from scietex.hal.vfd.intek import IntekSPEBModbusVFD
+
+
+async def main():
+    """Main function."""
+    vfd = IntekSPEBModbusVFD("gateway.local", port=502, unit_id=1)
+    await vfd.connect()
+    try:
+        print(await vfd.read_data())
+        print(await vfd.read_error_code())
+    finally:
+        await vfd.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+A Vesper drive behind the gateway works the same way:
+
+```python
+from scietex.hal.vfd.vesper import VesperE48400ModbusVFD
+
+vfd = VesperE48400ModbusVFD("gateway.local", port=502, unit_id=1)
+```
+
+`set_frequency` takes Hz, not percent: the caller works in engineering units and
+each driver converts with its own maximum-frequency parameter. The E5-8200's
+communication manual names no maximum-frequency parameter, so its driver takes
+`max_frequency_hz` from the constructor (default `50.0`, the factory base
+frequency); a caller whose drive runs a different maximum must pass it, or
+`frequency_percent` will be wrong.
+
+A drive that has never been configured for the gateway answers neither
+transport. See the per-family references for the register maps, the fault tables
+and the settings the gateway requires:
+
+- [`intek/docs/protocol.md`](src/scietex/hal/vfd/intek/docs/protocol.md) —
+  Intek SPE-B (`Pd.01`/`Pd.05`/`Pd.02`).
+- [`vesper/docs/README.md`](src/scietex/hal/vfd/vesper/docs/README.md) — Vesper
+  E5-8200 and E4-8400, plus the transport facts both manuals share.
+
+## Contributing
+
+Contributions are welcome! To contribute:
+
+1. Fork the repository.
+2. Create a feature branch (`git checkout -b feature/YourFeature`).
+3. Commit your changes (`git commit -m "Add your message"`).
+4. Push to the branch (`git push origin feature/YourFeature`).
+5. Open a Pull Request.
+
+Run the checks before opening a pull request:
+
+```bash
+tox -e format,lint,type,test
+```
+
+`format` and `lint` run `ruff`, `type` runs `ty`, and `test` runs `pytest` across
+Python 3.10, 3.12 and 3.14.
+
+## License
+
+This project is licensed under the **MIT License** - see the LICENSE file for details.

scietex_hal_vfd-2.0.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scietex.hal.vfd"
+dynamic = ["version"]
+description = "Scietex VFD HAL package"
+authors = [
+  { name = "Anton Bondarenko", email = "bond.anton@gmail.com" },
+]
+license = { file = "LICENSE" }
+readme = "README.md"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "msgspec[yaml] ~= 0.20.0",
+    "scietex.hal.serial >= 2.4.0, < 3.0.0",
+    "pymodbus ~= 3.15",
+]
+
+[project.entry-points."scietex.hal.vfd.drivers"]
+intek_spe_b_modbus = "scietex.hal.vfd.intek.spe_b:IntekSPEBModbusVFD"
+vesper_e5_8200_modbus = "scietex.hal.vfd.vesper.e5_8200:VesperE58200ModbusVFD"
+vesper_e4_8400_modbus = "scietex.hal.vfd.vesper.e4_8400:VesperE48400ModbusVFD"
+
+[project.entry-points."scietex.modbus.drivers"]
+intek_spe_b = "scietex.hal.vfd.modbus_drivers:intek_spe_b"
+vesper_e5_8200 = "scietex.hal.vfd.modbus_drivers:vesper_e5_8200"
+vesper_e4_8400 = "scietex.hal.vfd.modbus_drivers:vesper_e4_8400"
+
+[project.urls]
+"Homepage" = "https://github.com/bond-anton/scietex.hal.vfd"
+"Bug Tracker" = "https://github.com/bond-anton/scietex.hal.vfd/issues"
+
+[project.optional-dependencies]
+dev = ["tox>=4.46.0"]
+test = ["pytest", "pytest-asyncio", "pytest-xdist"]
+lint = ["ruff", "ty"]
+
+[tool.setuptools.dynamic]
+version = {attr = "scietex.hal.vfd.version.__version__"}
+
+[tool.setuptools.package-data]
+"scietex.hal.vfd" = ["py.typed"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = [
+  "src"
+]

scietex_hal_vfd-2.0.0/setup.cfg

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

scietex_hal_vfd-2.0.0/src/scietex/hal/vfd/__init__.py

@@ -0,0 +1,3 @@
+"""Scietex VFD HAL package."""
+
+from .version import __version__ as __version__

scietex_hal_vfd-2.0.0/src/scietex/hal/vfd/base/__init__.py

@@ -0,0 +1,47 @@
+"""
+Base VFD subpackage.
+
+Provides the transport-agnostic driver contract, the capability model, the
+shared data structures, and the RS485 base class the direct-serial drivers
+derive from.
+
+Classes:
+    VFD: Base class for drivers that own a serial connection.
+    VFDCapabilities: The control surface of one drive.
+    VFDError: A fault code paired with its message.
+    VFDParameters: A snapshot of the drive's operating parameters.
+    VFDProtocol: The contract every driver implements.
+    VFDState: The drive run state.
+
+Modules:
+    protocol: Defines the `VFDProtocol` driver contract.
+    capabilities: Defines the `VFDCapabilities` model.
+    data: Defines the data structures shared by every driver.
+    rs485: Defines the `VFD` serial base class.
+"""
+
+from .capabilities import VFDCapabilities
+from .data import (
+    VFDClearErrorCMD,
+    VFDError,
+    VFDParameters,
+    VFDSetFrequencyCMD,
+    VFDStartCMD,
+    VFDState,
+    VFDStopCMD,
+)
+from .protocol import VFDProtocol
+from .rs485 import VFD
+
+__all__ = [
+    "VFD",
+    "VFDCapabilities",
+    "VFDClearErrorCMD",
+    "VFDError",
+    "VFDParameters",
+    "VFDProtocol",
+    "VFDSetFrequencyCMD",
+    "VFDStartCMD",
+    "VFDState",
+    "VFDStopCMD",
+]

scietex_hal_vfd-2.0.0/src/scietex/hal/vfd/base/capabilities.py

@@ -0,0 +1,49 @@
+"""
+VFD capability model.
+
+A drive advertises what it can do through a single :class:`VFDCapabilities`
+value. The fields are the operations a caller can dispatch without inspecting
+the driver: whether the drive accepts a direction choice, a jog command, a
+coasting stop, a fault reset, and a frequency setpoint.
+
+The set is a frozen dataclass so a driver declares it once as a class attribute
+and callers cannot mutate it.
+
+Capabilities describe the *control* surface only. Whether a drive reports a
+particular *reading* — a heatsink temperature, a DC bus voltage — is answered by
+the corresponding :class:`scietex.hal.vfd.base.data.VFDParameters` field being
+``None``, not by a flag here. One source of truth cannot drift from the driver.
+
+Classes:
+    VFDCapabilities: The control surface of one drive.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class VFDCapabilities:
+    """
+    The control surface of one drive.
+
+    Every field defaults to "unsupported", so a driver declares only what its
+    hardware exposes. Read-side operations (parameters, state, error code) are
+    mandatory for every driver and are therefore not advertised here.
+
+    Attributes:
+        direction (bool): Whether the drive can be started in either rotation
+            direction. ``False`` means forward only.
+        jog (bool): Whether the drive accepts a jog command.
+        freewheel_stop (bool): Whether the drive can stop by coasting instead of
+            ramping down.
+        fault_reset (bool): Whether the drive accepts an explicit fault reset.
+        frequency_setpoint (bool): Whether the drive accepts a frequency
+            setpoint over the communication protocol, independent of the
+            keypad or an analog input.
+    """
+
+    direction: bool = True
+    jog: bool = False
+    freewheel_stop: bool = False
+    fault_reset: bool = False
+    frequency_setpoint: bool = False