scietex.hal.vfd 2.0.0__py3-none-any.whl

scietex/hal/vfd/__init__.py

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

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

scietex/hal/vfd/base/data.py

@@ -0,0 +1,122 @@
+"""VFD data structures.
+
+:class:`VFDParameters` names the operating frequency ``frequency_hz`` so it
+cannot be confused with ``frequency_percent``, which is the unit some drives
+report natively. The two frequency fields are the only ones guaranteed to be
+populated; every other field is optional and stays ``None`` when the drive's
+protocol does not expose it.
+
+``None`` and ``0.0`` mean different things throughout this module: ``None`` is
+"this drive does not report the value", ``0.0`` is "the drive reports zero".
+A caller that plots a temperature must check for ``None`` rather than treating
+a missing reading as a cold drive.
+"""
+
+from enum import Enum
+
+import msgspec
+
+
+class VFDState(Enum):
+    """Possible states of a Variable Frequency Drive (VFD)."""
+
+    UNKNOWN = 0
+    STOPPED = 1
+    RUNNING_FORWARD = 2
+    RUNNING_BACKWARD = 3  # or RUNNING_REVERSE
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation."""
+        return self.name.replace("_", " ").title()
+
+
+class VFDError(msgspec.Struct, frozen=True):
+    """Model of a VFD error with code and message."""
+
+    code: int
+    message: str = "Unknown error"
+
+    def __str__(self) -> str:
+        return f"VFDError(code={self.code}, message='{self.message}')"
+
+
+class VFDParameters(msgspec.Struct, frozen=True):
+    """Model for VFD operational parameters.
+
+    Attributes:
+        frequency_hz: Output frequency in Hz.
+        frequency_percent: Output frequency as a percentage of the configured
+            maximum, 0-100.
+        output_current: Output current in Amps.
+        output_voltage: Output voltage in Volts.
+        output_power: Output power in kW.
+        dc_bus_voltage: DC bus (link) voltage in Volts, or ``None`` when the
+            drive does not report it.
+        heatsink_temperature_c: Power-module or heatsink temperature in degrees
+            Celsius, or ``None`` when the drive does not report it. A drive that
+            signals overheat only through a fault code reports ``None`` here:
+            a fault is not a temperature.
+        motor_temperature_c: Motor winding or PTC temperature in degrees
+            Celsius, or ``None`` when the drive does not report it.
+        state: Current VFD state.
+    """
+
+    frequency_hz: float  # Current operating frequency in Hz
+    frequency_percent: float  # Frequency as a percentage of max (0-100%)
+    output_current: float = 0.0  # Output current in Amps
+    output_voltage: float = 0.0  # Output voltage in Volts
+    output_power: float = 0.0  # Output power in kW
+    dc_bus_voltage: float | None = None  # DC bus voltage in Volts
+    heatsink_temperature_c: float | None = None  # Power-module temperature, deg C
+    motor_temperature_c: float | None = None  # Motor temperature, deg C
+    state: VFDState = VFDState.STOPPED  # Current VFD state
+
+    def __str__(self) -> str:
+        return (
+            f"VFDParameters(frequency={self.frequency_hz} Hz, "
+            f"frequency_percent={self.frequency_percent}%, "
+            f"current={self.output_current} A, "
+            f"voltage={self.output_voltage} V, "
+            f"power={self.output_power} kW, "
+            f"dc_bus={self.dc_bus_voltage} V, "
+            f"heatsink={self.heatsink_temperature_c} C, "
+            f"motor={self.motor_temperature_c} C, "
+            f"state={self.state})"
+        )
+
+
+class VFDStartCMD(msgspec.Struct, frozen=True):
+    """VFD start command."""
+
+    forward: bool = True
+    slow: bool = False
+
+    def __str__(self) -> str:
+        return f"VFDStartCMD(forward={self.forward}, slow={self.slow})"
+
+
+class VFDStopCMD(msgspec.Struct, frozen=True):
+    """VFD stop command."""
+
+    freewheel: bool = False
+
+    def __str__(self) -> str:
+        return f"VFDStopCMD(freewheel={self.freewheel})"
+
+
+class VFDClearErrorCMD(msgspec.Struct, frozen=True):
+    """VFD clear error command."""
+
+    communication: bool = False
+
+    def __str__(self) -> str:
+        return f"VFDClearErrorCMD(communication={self.communication})"
+
+
+class VFDSetFrequencyCMD(msgspec.Struct, frozen=True):
+    """VFD frequency setpoint command."""
+
+    frequency_hz: float = 0.0
+
+    def __str__(self) -> str:
+        return f"VFDSetFrequencyCMD(frequency_hz={self.frequency_hz})"

scietex/hal/vfd/base/protocol.py

@@ -0,0 +1,129 @@
+"""
+VFD protocol.
+
+This module defines the transport-agnostic contract every variable frequency
+drive driver implements, plus the capability model that tells a caller which
+optional control operations a given drive supports. The contract is deliberately
+narrow: a driver must be able to connect, disconnect, read the operating
+parameters and state, read and reset the fault code, start and stop the motor,
+and set the frequency. Everything else — a jog command, for example — is
+advertised through :attr:`VFDProtocol.capabilities`, so a caller can reject an
+unsupported command before dispatching it instead of catching an exception after
+the fact.
+
+The same contract covers both transports in this package: the direct RS485
+clients derived from :class:`scietex.hal.vfd.base.rs485.VFD` and the Modbus/TCP
+clients that address a drive through the Scietex Modbus gateway.
+
+Classes:
+    VFDProtocol: The runtime-checkable protocol every drive driver satisfies.
+"""
+
+from typing import Any, Protocol, runtime_checkable
+
+from .capabilities import VFDCapabilities
+from .data import VFDParameters, VFDState
+
+
+@runtime_checkable
+class VFDProtocol(Protocol):
+    """
+    Contract implemented by every variable frequency drive driver.
+
+    Attributes:
+        label (str): Human-readable drive label, unique within a service.
+        capabilities (VFDCapabilities): What this drive can do.
+        display_name (str): Model name reported to the user interface.
+    """
+
+    label: str
+
+    capabilities: VFDCapabilities = VFDCapabilities()
+    display_name: str = "VFD"
+
+    async def connect(self) -> None:
+        """Open the transport to the drive."""
+
+    async def close(self) -> None:
+        """Close the transport to the drive."""
+
+    async def read_data(self) -> dict[str, Any]:
+        """
+        Read a snapshot of the drive's current values.
+
+        Returns:
+            dict[str, Any]: Field name to value mapping. ``state`` is always
+                present; the remaining keys depend on the driver.
+        """
+
+    async def read_parameters(self) -> VFDParameters:
+        """
+        Read the drive's operating parameters.
+
+        Returns:
+            VFDParameters: Frequency in both Hz and percent of the configured
+                maximum, output current, voltage, power and state, plus the
+                optional DC bus voltage and temperatures the drive reports.
+        """
+
+    async def read_state(self) -> VFDState:
+        """
+        Read the drive's run state.
+
+        Returns:
+            VFDState: The state, or ``VFDState.UNKNOWN`` when the drive reports
+                a value the protocol does not define.
+        """
+
+    async def read_error_code(self, comm: bool = False) -> int:
+        """
+        Read the latched fault code.
+
+        Args:
+            comm: Read the communication-protocol fault code instead of the
+                drive fault code.
+
+        Returns:
+            int: The fault code; ``0`` means no fault.
+        """
+
+    async def clear_error(self, comm: bool = False) -> int:
+        """
+        Reset the latched fault and read the code back.
+
+        Args:
+            comm: Reset the communication-protocol fault instead of the drive
+                fault.
+
+        Returns:
+            int: The fault code read after the reset; ``0`` means the fault is
+                gone.
+        """
+
+    async def start(self, forward: bool = True, slow: bool = False) -> None:
+        """
+        Start the motor.
+
+        Args:
+            forward: Run in the forward direction; ``False`` runs in reverse.
+            slow: Use the jog (slow) command instead of the normal run command.
+        """
+
+    async def stop(self, freewheel: bool = False) -> None:
+        """
+        Stop the motor.
+
+        Args:
+            freewheel: Coast to a stop instead of ramping down.
+        """
+
+    async def set_frequency(self, frequency_hz: float) -> None:
+        """
+        Set the frequency setpoint.
+
+        The value is in Hz, not percent: the caller works in engineering units
+        and each driver converts with its own maximum-frequency parameter.
+
+        Args:
+            frequency_hz: The requested output frequency in Hz.
+        """

scietex/hal/vfd/base/rs485.py

@@ -0,0 +1,153 @@
+"""Basic VFD device prototype class to be inherited by particular implementations."""
+
+from logging import Logger
+from typing import Any
+
+from scietex.hal.serial import (
+    ModbusSerialConnectionConfig,
+    RS485Client,
+    SerialConnectionConfig,
+)
+
+from .capabilities import VFDCapabilities
+from .data import (
+    VFDClearErrorCMD,
+    VFDError,
+    VFDParameters,
+    VFDSetFrequencyCMD,
+    VFDStartCMD,
+    VFDState,
+    VFDStopCMD,
+)
+from .protocol import VFDProtocol
+
+
+class VFD(RS485Client, VFDProtocol):
+    """VFD control base class"""
+
+    capabilities = VFDCapabilities()
+    display_name = "VFD"
+
+    def __init__(
+        self,
+        con_params: SerialConnectionConfig | ModbusSerialConnectionConfig,
+        address: int = 1,
+        label: str = "VFD",
+        logger: Logger | None = None,
+        **kwargs,
+    ):
+        super().__init__(
+            con_params=con_params,
+            address=address,
+            label=label,
+            logger=logger,
+            **kwargs,
+        )
+        self.error_codes: dict[int, VFDError] = {0: VFDError(code=0, message="No error")}
+        self.error_codes_com: dict[int, VFDError] = {0: VFDError(code=0, message="No error")}
+
+    async def connect(self) -> None:
+        """Nothing to do: the serial client opens the port once per operation."""
+        self.logger.debug("%s: Connect (per-operation serial client).", self.label)
+
+    # Errors processing methods
+    async def read_error_code(self, comm: bool = False) -> int:
+        """Read error code from the VFD"""
+        code = 0
+        if comm:
+            self.logger.debug("%s: Communication error code %d.", self.label, code)
+        else:
+            self.logger.debug("%s: Error code %d.", self.label, code)
+        return code
+
+    def parse_error_code(self, code: int, comm: bool = False) -> VFDError:
+        """Parse error code from the VFD"""
+        if comm:
+            if code in self.error_codes_com:
+                return self.error_codes_com[code]
+        else:
+            if code in self.error_codes:
+                return self.error_codes[code]
+        return VFDError(code=code, message="Unknown error")
+
+    async def clear_error(self, comm: bool = False) -> int:
+        """Clear error from the VFD"""
+        if comm:
+            self.logger.debug("%s: Clear communication error.", self.label)
+        else:
+            self.logger.debug("%s: Clear error.", self.label)
+        return await self.read_error_code(comm)
+
+    # Parameters monitoring methods
+    async def read_parameters(self) -> VFDParameters:
+        """Read the VFD operating parameters"""
+        parameters = VFDParameters(frequency_hz=0.0, frequency_percent=0.0)
+        self.logger.debug("%s: %s", self.label, parameters)
+        return parameters
+
+    async def read_state(self) -> VFDState:
+        """Read the VFD run state"""
+        state = VFDState.UNKNOWN
+        self.logger.debug("%s: Current state: %s", self.label, state)
+        return state
+
+    # VFD Control methods
+    async def start(self, forward: bool = True, slow: bool = False) -> None:
+        """Start the VFD"""
+        self.logger.debug("%s: Start (forward: %s, slow: %s)", self.label, forward, slow)
+
+    async def stop(self, freewheel: bool = False) -> None:
+        """Stop the VFD"""
+        self.logger.debug("%s: Stop (freewheel: %s)", self.label, freewheel)
+
+    async def set_frequency(self, frequency_hz: float) -> None:
+        """Set the VFD frequency setpoint"""
+        self.logger.debug("%s: Set frequency %s Hz.", self.label, frequency_hz)
+
+    async def read_data(self) -> dict[str, Any]:
+        """
+        Read the VFD operating parameters as a plain dictionary.
+
+        The return type is widened to ``Any`` because `VFDParameters` carries
+        optional fields (temperatures, DC bus voltage) that are ``None`` when the
+        drive does not report them, which the inherited `RS485Client` signature
+        does not allow.
+        """
+        parameters = await self.read_parameters()
+        return {f: getattr(parameters, f) for f in parameters.__struct_fields__}
+
+    async def process_message(self, message: dict[str, Any]) -> None:
+        await super().process_message(message)
+        if "cmd" in message:
+            if message["cmd"] == "start":
+                start_params = VFDStartCMD()
+                if "data" in message:
+                    try:
+                        start_params = VFDStartCMD(**message["data"])
+                    except (TypeError, ValueError):
+                        pass
+                await self.start(forward=start_params.forward, slow=start_params.slow)
+            elif message["cmd"] == "stop":
+                stop_params = VFDStopCMD()
+                if "data" in message:
+                    try:
+                        stop_params = VFDStopCMD(**message["data"])
+                    except (TypeError, ValueError):
+                        pass
+                await self.stop(freewheel=stop_params.freewheel)
+            elif message["cmd"] == "clear_error":
+                clear_params = VFDClearErrorCMD()
+                if "data" in message:
+                    try:
+                        clear_params = VFDClearErrorCMD(**message["data"])
+                    except (TypeError, ValueError):
+                        pass
+                await self.clear_error(comm=clear_params.communication)
+            elif message["cmd"] == "set_frequency":
+                frequency_params = VFDSetFrequencyCMD()
+                if "data" in message:
+                    try:
+                        frequency_params = VFDSetFrequencyCMD(**message["data"])
+                    except (TypeError, ValueError):
+                        pass
+                await self.set_frequency(frequency_hz=frequency_params.frequency_hz)

scietex/hal/vfd/intek/__init__.py

@@ -0,0 +1,5 @@
+"""Intek VFDs"""
+
+from .spe_b import IntekSPEBModbusVFD, SPEvB
+
+__all__ = ["IntekSPEBModbusVFD", "SPEvB"]

scietex/hal/vfd/intek/spe_b/__init__.py

@@ -0,0 +1,26 @@
+"""
+Intek SPE-B drivers.
+
+Two transports are supported for the same register map:
+
+- :class:`SPEvB` talks Modbus RTU to the drive over a direct serial connection.
+- :class:`IntekSPEBModbusVFD` talks Modbus/TCP to the Scietex Modbus gateway,
+  which owns the serial bus and routes requests to the drive by unit id.
+
+Modules:
+    registers: Register addresses, control and status codes, scaling helpers.
+    errors: Drive and communication fault code tables.
+    rs485: The direct-serial client.
+    client: The Modbus/TCP gateway client.
+"""
+
+from .client import IntekSPEBModbusVFD
+from .errors import SPE_B_ERROR_CODES, SPE_B_ERROR_CODES_COM
+from .rs485 import SPEvB
+
+__all__ = [
+    "IntekSPEBModbusVFD",
+    "SPE_B_ERROR_CODES",
+    "SPE_B_ERROR_CODES_COM",
+    "SPEvB",
+]