scietex.hal.vfd 2.0.0__tar.gz → 2.0.2__tar.gz

{scietex_hal_vfd-2.0.0/src/scietex.hal.vfd.egg-info → scietex_hal_vfd-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scietex.hal.vfd
-Version: 2.0.0
+Version: 2.0.2
 Summary: Scietex VFD HAL package
 Author-email: Anton Bondarenko <bond.anton@gmail.com>
 License: MIT License
@@ -86,7 +86,7 @@ A driver reaches a drive over one of two transports:
 
 | Field | Intek SPE-B | Vesper E5-8200 | Vesper E4-8400 |
 | --- | --- | --- | --- |
-| `frequency_hz` | yes | yes | yes |
+| `frequency_hz` | yes¹ | yes | yes |
 | `frequency_percent` | yes | yes | yes |
 | `output_current` | yes | yes | yes |
 | `output_voltage` | yes | yes | yes |
@@ -98,6 +98,12 @@ A driver reaches a drive over one of two transports:
 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.
 
+¹ The SPE-B reports the operating frequency only as a percentage of `P0.10`, so
+`frequency_hz` is `None` until `P0.10` has been read. A drive that refuses
+`P0.10` still reports `frequency_percent`, current, voltage and power; the
+connection stays usable and only the Hz field degrades. `set_frequency` is
+refused in that state, because no percentage can be computed.
+
 ## Installation
 
 Install the package via pip (assuming it's published to PyPI):

{scietex_hal_vfd-2.0.0 → scietex_hal_vfd-2.0.2}/README.md

@@ -38,7 +38,7 @@ A driver reaches a drive over one of two transports:
 
 | Field | Intek SPE-B | Vesper E5-8200 | Vesper E4-8400 |
 | --- | --- | --- | --- |
-| `frequency_hz` | yes | yes | yes |
+| `frequency_hz` | yes¹ | yes | yes |
 | `frequency_percent` | yes | yes | yes |
 | `output_current` | yes | yes | yes |
 | `output_voltage` | yes | yes | yes |
@@ -50,6 +50,12 @@ A driver reaches a drive over one of two transports:
 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.
 
+¹ The SPE-B reports the operating frequency only as a percentage of `P0.10`, so
+`frequency_hz` is `None` until `P0.10` has been read. A drive that refuses
+`P0.10` still reports `frequency_percent`, current, voltage and power; the
+connection stays usable and only the Hz field degrades. `set_frequency` is
+refused in that state, because no percentage can be computed.
+
 ## Installation
 
 Install the package via pip (assuming it's published to PyPI):

{scietex_hal_vfd-2.0.0 → scietex_hal_vfd-2.0.2}/src/scietex/hal/vfd/base/data.py

@@ -44,7 +44,10 @@ class VFDParameters(msgspec.Struct, frozen=True):
     """Model for VFD operational parameters.
 
     Attributes:
-        frequency_hz: Output frequency in Hz.
+        frequency_hz: Output frequency in Hz, or ``None`` when the drive
+            reports the frequency only as a percentage and the maximum it is a
+            percentage of is unknown. ``None`` rather than 0.0 because the drive
+            has not reported a frequency of zero — it has reported nothing.
         frequency_percent: Output frequency as a percentage of the configured
             maximum, 0-100.
         output_current: Output current in Amps.
@@ -61,7 +64,7 @@ class VFDParameters(msgspec.Struct, frozen=True):
         state: Current VFD state.
     """
 
-    frequency_hz: float  # Current operating frequency in Hz
+    frequency_hz: float | None  # 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

{scietex_hal_vfd-2.0.0 → scietex_hal_vfd-2.0.2}/src/scietex/hal/vfd/base/rs485.py

@@ -4,6 +4,7 @@ from logging import Logger
 from typing import Any
 
 from scietex.hal.serial import (
+    ModbusOperationError,
     ModbusSerialConnectionConfig,
     RS485Client,
     SerialConnectionConfig,
@@ -116,6 +117,29 @@ class VFD(RS485Client, VFDProtocol):
         parameters = await self.read_parameters()
         return {f: getattr(parameters, f) for f in parameters.__struct_fields__}
 
+    async def _read_optional_register(self, register: int) -> int | None:
+        """
+        Read one register, returning ``None`` instead of raising on failure.
+
+        Used for readings that refine a snapshot but must not fail it: a drive
+        that refuses one diagnostic register still reports its frequency,
+        current and state, and a poll loop that raised on every optional read
+        would never publish anything.
+
+        Args:
+            register: The holding register address.
+
+        Returns:
+            int | None: The register value, or ``None`` when the read failed.
+        """
+        try:
+            return await self.read_register(register, holding=True)
+        except ModbusOperationError as exc:
+            self.logger.warning(
+                "%s: Optional register %s is unreadable (%s).", self.label, register, exc
+            )
+            return None
+
     async def process_message(self, message: dict[str, Any]) -> None:
         await super().process_message(message)
         if "cmd" in message:

{scietex_hal_vfd-2.0.0 → scietex_hal_vfd-2.0.2}/src/scietex/hal/vfd/intek/spe_b/client.py

@@ -103,11 +103,13 @@ class IntekSPEBModbusVFD(VFDProtocol):
         Open the TCP connection to the gateway and read the drive's scale factors.
 
         Raises:
-            ModbusOperationError: If the gateway is unreachable, or if P0.10
-                cannot be read. pymodbus reports a failed connect by returning
-                ``False`` rather than raising, so the result is checked here;
-                otherwise an unreachable drive would look connected and only
-                fail on the first read.
+            ModbusOperationError: If the gateway is unreachable. pymodbus
+                reports a failed connect by returning ``False`` rather than
+                raising, so the result is checked here; otherwise an
+                unreachable drive would look connected and only fail on the
+                first read. An unreadable P0.10 is not an error: the drive
+                still reports its measurements, only ``frequency_hz`` degrades
+                to ``None``.
         """
         if self._client is None:
             self._client = AsyncModbusTcpClient(self._host, port=self._port, timeout=self._timeout)
@@ -157,6 +159,31 @@ class IntekSPEBModbusVFD(VFDProtocol):
             )
         return list(response.registers)
 
+    async def _read_optional_registers(self, address: int, count: int) -> list[int] | None:
+        """
+        Read holding registers, returning ``None`` instead of raising on failure.
+
+        Used for readings that refine a snapshot but must not fail it: a drive
+        that refuses one diagnostic register still reports its frequency,
+        current and state, and a poll loop that raised on every optional read
+        would never publish anything.
+
+        Args:
+            address: Starting register address.
+            count: Number of registers to read.
+
+        Returns:
+            list[int] | None: The register values, or ``None`` when the read
+                failed.
+        """
+        try:
+            return await self._read_registers(address, count)
+        except ModbusOperationError as exc:
+            self.logger.warning(
+                "%s: Optional register %s is unreadable (%s).", self.label, address, exc
+            )
+            return None
+
     async def _write_register(self, address: int, value: int) -> None:
         """
         Write a single holding register, raising on a Modbus exception response.
@@ -180,16 +207,25 @@ class IntekSPEBModbusVFD(VFDProtocol):
         """
         Read and cache the P0.10 maximum frequency and the Pd.06 resolution.
 
-        Raises:
-            ModbusOperationError: If P0.10 cannot be read, because every
-                frequency this client reports would then be a guess.
+        P0.10 is optional: a drive that refuses it still reports its operating
+        percentage, current, voltage and power, so the connection stays usable
+        and only ``frequency_hz`` degrades to ``None``. Raising here would make
+        the poll loop log a connect failure every cycle and publish nothing at
+        all, which is what an SPE-B that has not been configured for Modbus
+        (Pd.01/Pd.05) does — it answers the gateway with exception 11.
         """
-        raw = await self._read_registers(registers.PARAM_MAX_FREQUENCY_EEPROM, 1)
-        self._max_frequency_hz = raw[0] / registers.PARAMETER_FREQUENCY_RESOLUTION
-        if self._max_frequency_hz <= 0:
+        try:
+            raw = await self._read_registers(registers.PARAM_MAX_FREQUENCY_EEPROM, 1)
+        except ModbusOperationError as exc:
             self.logger.warning(
-                "%s: P0.10 reads %d, frequency is reported as 0 Hz.", self.label, raw[0]
+                "%s: P0.10 is unreadable (%s), frequency is reported as None.", self.label, exc
             )
+        else:
+            self._max_frequency_hz = raw[0] / registers.PARAMETER_FREQUENCY_RESOLUTION
+            if self._max_frequency_hz <= 0:
+                self.logger.warning(
+                    "%s: P0.10 reads %d, frequency is reported as None.", self.label, raw[0]
+                )
         # Pd.06 only refines the current reading, so a drive that refuses the
         # read keeps working with the factory resolution instead of failing
         # the connection: stop and fault reset must stay available.
@@ -204,7 +240,7 @@ class IntekSPEBModbusVFD(VFDProtocol):
             else registers.CURRENT_RESOLUTION_FINE
         )
 
-    def _percent_to_hz(self, percent: float) -> float:
+    def _percent_to_hz(self, percent: float) -> float | None:
         """
         Convert an operating frequency percentage into Hz.
 
@@ -212,10 +248,13 @@ class IntekSPEBModbusVFD(VFDProtocol):
             percent: Frequency as reported by the drive.
 
         Returns:
-            float: The frequency in Hz, or 0.0 while P0.10 is unknown.
+            float | None: The frequency in Hz, or ``None`` while P0.10 is
+                unknown. ``None`` rather than 0.0 because a drive that refuses
+                P0.10 has not reported a frequency of zero — it has reported
+                nothing, and a caller must be able to tell the two apart.
         """
         if self._max_frequency_hz <= 0:
-            return 0.0
+            return None
         return registers.percent_to_hz(percent, self._max_frequency_hz)
 
     async def read_parameters(self) -> VFDParameters:
@@ -227,9 +266,16 @@ class IntekSPEBModbusVFD(VFDProtocol):
         drive sends them, because the manual states no scaling factor for
         either; current is scaled by the Pd.06 resolution.
 
+        The run state is read separately and is optional: a drive that refuses
+        the status register still reports its measurements, so the state falls
+        back to ``VFDState.UNKNOWN`` instead of failing the whole snapshot.
+
         Returns:
             VFDParameters: The decoded parameters. Both temperature fields are
                 ``None``: SPE-B reports overheat as a fault code, not a reading.
+
+        Raises:
+            ModbusOperationError: If the measurement block cannot be read.
         """
         block = await self._read_registers(
             registers.PARAMETERS_BLOCK_ADDRESS, registers.PARAMETERS_BLOCK_COUNT
@@ -264,10 +310,13 @@ class IntekSPEBModbusVFD(VFDProtocol):
         Read the drive's run state.
 
         Returns:
-            VFDState: The decoded state, or ``VFDState.UNKNOWN`` for a status
-                value the manual does not define.
+            VFDState: The decoded state, or ``VFDState.UNKNOWN`` when the status
+                register is unreadable or holds a value the manual does not
+                define.
         """
-        raw = await self._read_registers(registers.REG_STATUS, 1)
+        raw = await self._read_optional_registers(registers.REG_STATUS, 1)
+        if raw is None:
+            return VFDState.UNKNOWN
         state = registers.status_to_state(raw[0])
         self.logger.debug("%s: Current state: %s", self.label, state)
         return state

{scietex_hal_vfd-2.0.0 → scietex_hal_vfd-2.0.2}/src/scietex/hal/vfd/intek/spe_b/rs485.py

@@ -53,12 +53,22 @@ class SPEvB(VFD):
         self._current_resolution = registers.CURRENT_RESOLUTION_FINE
 
     async def _read_scale_factors(self) -> None:
-        """Read P0.10 and Pd.06 from the drive once and cache them."""
-        raw = await self.read_register(registers.PARAM_MAX_FREQUENCY_EEPROM, holding=True)
+        """
+        Read P0.10 and Pd.06 from the drive once and cache them.
+
+        P0.10 is optional: a drive that refuses it still reports its operating
+        percentage, current, voltage and power, so only ``frequency_hz``
+        degrades to ``None``. Raising here would fail the whole snapshot.
+        """
+        raw = await self.read_register(
+            registers.PARAM_MAX_FREQUENCY_EEPROM,
+            holding=True,
+            raise_on_error=False,
+        )
         self._max_frequency_hz = (raw or 0) / registers.PARAMETER_FREQUENCY_RESOLUTION
         if self._max_frequency_hz <= 0:
             self.logger.warning(
-                "%s: P0.10 reads %s, frequency is reported as 0 Hz.", self.label, raw
+                "%s: P0.10 reads %s, frequency is reported as None.", self.label, raw
             )
         # Pd.06 only refines the current reading, so a drive that refuses the
         # read keeps working with the factory resolution.
@@ -114,7 +124,7 @@ class SPEvB(VFD):
         frequency_hz = (
             registers.percent_to_hz(percent, self._max_frequency_hz)
             if self._max_frequency_hz
-            else 0.0
+            else None
         )
         state = await self.read_state()
         return VFDParameters(
@@ -135,7 +145,7 @@ class SPEvB(VFD):
 
     async def read_state(self) -> VFDState:
         """Read the VFD run state"""
-        status = await self.read_register(registers.REG_STATUS, holding=True)
+        status = await self._read_optional_register(registers.REG_STATUS)
         if status is None:
             return VFDState.UNKNOWN
         return registers.status_to_state(status)

{scietex_hal_vfd-2.0.0 → scietex_hal_vfd-2.0.2}/src/scietex/hal/vfd/version.py

@@ -5,4 +5,4 @@ Attributes:
     __version__ (str): The current version of the package.
 """
 
-__version__ = "2.0.0"
+__version__ = "2.0.2"

{scietex_hal_vfd-2.0.0 → scietex_hal_vfd-2.0.2}/src/scietex/hal/vfd/vesper/e4_8400/client.py

@@ -160,6 +160,31 @@ class VesperE48400ModbusVFD(VFDProtocol):
             )
         return list(response.registers)
 
+    async def _read_optional_registers(self, address: int, count: int) -> list[int] | None:
+        """
+        Read holding registers, returning ``None`` instead of raising on failure.
+
+        Used for readings that refine a snapshot but must not fail it: a drive
+        that refuses one diagnostic register still reports its frequency,
+        current and state, and a poll loop that raised on every optional read
+        would never publish anything.
+
+        Args:
+            address: Starting register address.
+            count: Number of registers to read.
+
+        Returns:
+            list[int] | None: The register values, or ``None`` when the read
+                failed.
+        """
+        try:
+            return await self._read_registers(address, count)
+        except ModbusOperationError as exc:
+            self.logger.warning(
+                "%s: Optional register %s is unreadable (%s).", self.label, address, exc
+            )
+            return None
+
     async def _write_register(self, address: int, value: int) -> None:
         """
         Write a single holding register, raising on a Modbus exception response.
@@ -221,13 +246,19 @@ class VesperE48400ModbusVFD(VFDProtocol):
         temperature are read separately because the gaps between them would
         otherwise pull in reserved registers.
 
+        The three separate readings and the run state are optional: a drive that
+        refuses one of them still reports its frequency and current, so the
+        affected field stays ``None`` (or ``VFDState.UNKNOWN``) instead of
+        failing the whole snapshot.
+
         Returns:
             VFDParameters: The decoded parameters. ``heatsink_temperature_c`` is
                 populated from U1-46; ``motor_temperature_c`` stays ``None``
                 because the drive reports motor overheat only as a fault.
 
         Raises:
-            ModbusOperationError: If any read fails.
+            ModbusOperationError: If the measurement block or E1-04 cannot be
+                read.
         """
         await self._read_max_frequency()
         block = await self._read_registers(
@@ -235,16 +266,16 @@ class VesperE48400ModbusVFD(VFDProtocol):
         )
         offset = registers.PARAMETERS_BLOCK_ADDRESS
         frequency_hz = registers.output_frequency_hz(block[registers.REG_OUTPUT_FREQUENCY - offset])
-        voltage = await self._read_registers(registers.REG_OUTPUT_VOLTAGE, 1)
-        dc_bus = await self._read_registers(registers.REG_DC_BUS_VOLTAGE, 1)
-        temperature = await self._read_registers(registers.REG_HEATSINK_TEMPERATURE, 1)
+        voltage = await self._read_optional_registers(registers.REG_OUTPUT_VOLTAGE, 1)
+        dc_bus = await self._read_optional_registers(registers.REG_DC_BUS_VOLTAGE, 1)
+        temperature = await self._read_optional_registers(registers.REG_HEATSINK_TEMPERATURE, 1)
         parameters = VFDParameters(
             frequency_hz=frequency_hz,
             frequency_percent=self._percent(frequency_hz),
             output_current=registers.output_current_a(block[registers.REG_OUTPUT_CURRENT - offset]),
-            output_voltage=float(voltage[0]),
-            dc_bus_voltage=float(dc_bus[0]),
-            heatsink_temperature_c=float(temperature[0]),
+            output_voltage=float(voltage[0]) if voltage is not None else 0.0,
+            dc_bus_voltage=float(dc_bus[0]) if dc_bus is not None else None,
+            heatsink_temperature_c=float(temperature[0]) if temperature is not None else None,
             state=await self.read_state(),
         )
         self.logger.debug("%s: %s", self.label, parameters)
@@ -255,12 +286,12 @@ class VesperE48400ModbusVFD(VFDProtocol):
         Read the drive's run state.
 
         Returns:
-            VFDState: The decoded state.
-
-        Raises:
-            ModbusOperationError: If the status register cannot be read.
+            VFDState: The decoded state, or ``VFDState.UNKNOWN`` when the status
+                register is unreadable.
         """
-        raw = await self._read_registers(registers.REG_STATUS, 1)
+        raw = await self._read_optional_registers(registers.REG_STATUS, 1)
+        if raw is None:
+            return VFDState.UNKNOWN
         state = registers.status_to_state(raw[0])
         self.logger.debug("%s: Current state: %s", self.label, state)
         return state

{scietex_hal_vfd-2.0.0 → scietex_hal_vfd-2.0.2}/src/scietex/hal/vfd/vesper/e4_8400/rs485.py

@@ -198,13 +198,19 @@ class VesperE48400(VFD):
         temperature are read separately because the gaps between them would
         otherwise pull in reserved registers.
 
+        The three separate readings and the run state are optional: a drive that
+        refuses one of them still reports its frequency and current, so the
+        affected field stays ``None`` (or ``VFDState.UNKNOWN``) instead of
+        failing the whole snapshot.
+
         Returns:
             VFDParameters: The decoded parameters. ``heatsink_temperature_c`` is
                 populated from U1-46; ``motor_temperature_c`` stays ``None``
                 because the drive reports motor overheat only as a fault.
 
         Raises:
-            ModbusOperationError: If any read fails.
+            ModbusOperationError: If the measurement block or E1-04 cannot be
+                read.
         """
         await self._read_max_frequency()
         block = await self.read_registers(
@@ -218,9 +224,9 @@ class VesperE48400(VFD):
             )
         offset = registers.PARAMETERS_BLOCK_ADDRESS
         frequency_hz = registers.output_frequency_hz(block[registers.REG_OUTPUT_FREQUENCY - offset])
-        voltage = await self.read_register(registers.REG_OUTPUT_VOLTAGE, holding=True)
-        dc_bus = await self.read_register(registers.REG_DC_BUS_VOLTAGE, holding=True)
-        temperature = await self.read_register(registers.REG_HEATSINK_TEMPERATURE, holding=True)
+        voltage = await self._read_optional_register(registers.REG_OUTPUT_VOLTAGE)
+        dc_bus = await self._read_optional_register(registers.REG_DC_BUS_VOLTAGE)
+        temperature = await self._read_optional_register(registers.REG_HEATSINK_TEMPERATURE)
         return VFDParameters(
             frequency_hz=frequency_hz,
             frequency_percent=self._percent(frequency_hz),
@@ -239,7 +245,7 @@ class VesperE48400(VFD):
             VFDState: The decoded state, or ``VFDState.UNKNOWN`` if the status
                 register cannot be read.
         """
-        status = await self.read_register(registers.REG_STATUS, holding=True)
+        status = await self._read_optional_register(registers.REG_STATUS)
         if status is None:
             return VFDState.UNKNOWN
         return registers.status_to_state(status)

{scietex_hal_vfd-2.0.0 → scietex_hal_vfd-2.0.2}/src/scietex/hal/vfd/vesper/e5_8200/client.py

@@ -156,6 +156,31 @@ class VesperE58200ModbusVFD(VFDProtocol):
             )
         return list(response.registers)
 
+    async def _read_optional_registers(self, address: int, count: int) -> list[int] | None:
+        """
+        Read holding registers, returning ``None`` instead of raising on failure.
+
+        Used for readings that refine a snapshot but must not fail it: a drive
+        that refuses one diagnostic register still reports its frequency,
+        current and state, and a poll loop that raised on every optional read
+        would never publish anything.
+
+        Args:
+            address: Starting register address.
+            count: Number of registers to read.
+
+        Returns:
+            list[int] | None: The register values, or ``None`` when the read
+                failed.
+        """
+        try:
+            return await self._read_registers(address, count)
+        except ModbusOperationError as exc:
+            self.logger.warning(
+                "%s: Optional register %s is unreadable (%s).", self.label, address, exc
+            )
+            return None
+
     async def _write_register(self, address: int, value: int) -> None:
         """
         Write a single holding register, raising on a Modbus exception response.
@@ -198,11 +223,15 @@ class VesperE58200ModbusVFD(VFDProtocol):
         field stays 0.0, and no temperature, so both temperature fields stay
         ``None``.
 
+        The run state is read separately and is optional: a drive that refuses
+        the monitor register still reports its measurements, so the state falls
+        back to ``VFDState.UNKNOWN`` instead of failing the whole snapshot.
+
         Returns:
             VFDParameters: The decoded parameters.
 
         Raises:
-            ModbusOperationError: If the block cannot be read.
+            ModbusOperationError: If the measurement block cannot be read.
         """
         block = await self._read_registers(
             registers.PARAMETERS_BLOCK_ADDRESS, registers.PARAMETERS_BLOCK_COUNT
@@ -225,12 +254,12 @@ class VesperE58200ModbusVFD(VFDProtocol):
         Read the drive's run state.
 
         Returns:
-            VFDState: The decoded state.
-
-        Raises:
-            ModbusOperationError: If the monitor register cannot be read.
+            VFDState: The decoded state, or ``VFDState.UNKNOWN`` when the monitor
+                register is unreadable.
         """
-        raw = await self._read_registers(registers.REG_MONITOR, 1)
+        raw = await self._read_optional_registers(registers.REG_MONITOR, 1)
+        if raw is None:
+            return VFDState.UNKNOWN
         state = registers.status_to_state(raw[0])
         self.logger.debug("%s: Current state: %s", self.label, state)
         return state

{scietex_hal_vfd-2.0.0 → scietex_hal_vfd-2.0.2}/src/scietex/hal/vfd/vesper/e5_8200/rs485.py

@@ -133,11 +133,15 @@ class VesperE58200(VFD):
         field stays 0.0, and no temperature, so both temperature fields stay
         ``None``.
 
+        The run state is read separately and is optional: a drive that refuses
+        the monitor register still reports its measurements, so the state falls
+        back to ``VFDState.UNKNOWN`` instead of failing the whole snapshot.
+
         Returns:
             VFDParameters: The decoded parameters.
 
         Raises:
-            ModbusOperationError: If the block cannot be read.
+            ModbusOperationError: If the measurement block cannot be read.
         """
         block = await self.read_registers(
             registers.PARAMETERS_BLOCK_ADDRESS,
@@ -167,7 +171,7 @@ class VesperE58200(VFD):
             VFDState: The decoded state, or ``VFDState.UNKNOWN`` if the monitor
                 register cannot be read.
         """
-        monitor = await self.read_register(registers.REG_MONITOR, holding=True)
+        monitor = await self._read_optional_register(registers.REG_MONITOR)
         if monitor is None:
             return VFDState.UNKNOWN
         return registers.status_to_state(monitor)

{scietex_hal_vfd-2.0.0 → scietex_hal_vfd-2.0.2/src/scietex.hal.vfd.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scietex.hal.vfd
-Version: 2.0.0
+Version: 2.0.2
 Summary: Scietex VFD HAL package
 Author-email: Anton Bondarenko <bond.anton@gmail.com>
 License: MIT License
@@ -86,7 +86,7 @@ A driver reaches a drive over one of two transports:
 
 | Field | Intek SPE-B | Vesper E5-8200 | Vesper E4-8400 |
 | --- | --- | --- | --- |
-| `frequency_hz` | yes | yes | yes |
+| `frequency_hz` | yes¹ | yes | yes |
 | `frequency_percent` | yes | yes | yes |
 | `output_current` | yes | yes | yes |
 | `output_voltage` | yes | yes | yes |
@@ -98,6 +98,12 @@ A driver reaches a drive over one of two transports:
 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.
 
+¹ The SPE-B reports the operating frequency only as a percentage of `P0.10`, so
+`frequency_hz` is `None` until `P0.10` has been read. A drive that refuses
+`P0.10` still reports `frequency_percent`, current, voltage and power; the
+connection stays usable and only the Hz field degrades. `set_frequency` is
+refused in that state, because no percentage can be computed.
+
 ## Installation
 
 Install the package via pip (assuming it's published to PyPI):

{scietex_hal_vfd-2.0.0 → scietex_hal_vfd-2.0.2}/src/scietex.hal.vfd.egg-info/SOURCES.txt

@@ -38,4 +38,5 @@ tests/test_modbus_drivers.py
 tests/test_registers.py
 tests/test_version.py
 tests/test_vesper_e4_8400_registers.py
-tests/test_vesper_e5_8200_registers.py
+tests/test_vesper_e5_8200_registers.py
+tests/test_vesper_optional_reads.py

{scietex_hal_vfd-2.0.0 → scietex_hal_vfd-2.0.2}/tests/test_modbus_client.py

@@ -159,12 +159,76 @@ def test_read_parameters_uses_the_coarse_current_resolution():
     assert asyncio.run(vfd.read_parameters()).output_current == pytest.approx(12.3)
 
 
-def test_read_parameters_reports_zero_hz_when_p010_is_zero():
-    """An unreadable maximum frequency keeps the percentage but cannot scale it."""
+def test_read_parameters_reports_no_hz_when_p010_is_zero():
+    """An unusable maximum frequency keeps the percentage but cannot scale it."""
     vfd, _ = _connected([_read([5000, 0, 0, 0, 0]), _read([3])], max_frequency_raw=0)
     parameters = asyncio.run(vfd.read_parameters())
     assert parameters.frequency_percent == pytest.approx(50.0)
-    assert parameters.frequency_hz == pytest.approx(0.0)
+    assert parameters.frequency_hz is None
+
+
+def test_connect_survives_a_refused_p010_and_still_reports_measurements():
+    """A drive that refuses P0.10 must not blank the whole snapshot.
+
+    An SPE-B that has not been configured for Modbus (Pd.01/Pd.05) answers the
+    gateway with exception 11 for every register. Raising from `connect()` made
+    the poll loop log a connect failure every cycle and publish nothing; the
+    percentage, current, voltage and power are still readable, so only
+    `frequency_hz` degrades to None.
+    """
+    stub = _StubClient(
+        [
+            ExceptionResponse(function_code=3),  # P0.10
+            _read([1]),  # Pd.06 = coarse, 0.1 A
+            _read([5000, 540, 380, 123, 45]),
+            _read([1]),  # status: running forward
+        ]
+    )
+    vfd = IntekSPEBModbusVFD("127.0.0.1")
+    vfd._client = stub
+    asyncio.run(vfd.connect())
+    parameters = asyncio.run(vfd.read_parameters())
+    assert parameters.frequency_percent == pytest.approx(50.0)
+    assert parameters.frequency_hz is None
+    assert parameters.output_current == pytest.approx(12.3)
+    assert parameters.output_voltage == pytest.approx(380.0)
+    assert parameters.dc_bus_voltage == pytest.approx(540.0)
+    assert parameters.state is VFDState.RUNNING_FORWARD
+
+
+def test_set_frequency_still_refuses_when_p010_is_unknown():
+    """Without P0.10 no percentage can be computed, so the write is rejected."""
+    vfd, _ = _connected([], max_frequency_raw=0)
+    with pytest.raises(ValueError, match="P0.10"):
+        asyncio.run(vfd.set_frequency(25.0))
+
+
+def test_read_parameters_survives_an_unreadable_status_register():
+    """A refused status read must not discard the measurements.
+
+    The poll loop publishes whatever `read_parameters` returns; raising here
+    would mean a drive that refuses one diagnostic register never reports its
+    frequency, current or voltage at all.
+    """
+    vfd, _ = _connected([_read([5000, 540, 380, 123, 45]), ExceptionResponse(function_code=3)])
+    parameters = asyncio.run(vfd.read_parameters())
+    assert parameters.frequency_hz == pytest.approx(25.0)
+    assert parameters.output_current == pytest.approx(1.23)
+    assert parameters.output_voltage == pytest.approx(380.0)
+    assert parameters.state is VFDState.UNKNOWN
+
+
+def test_read_parameters_still_raises_when_the_measurement_block_fails():
+    """The measurement block is mandatory: without it there is nothing to report."""
+    vfd, _ = _connected([ExceptionResponse(function_code=3)])
+    with pytest.raises(ModbusOperationError):
+        asyncio.run(vfd.read_parameters())
+
+
+def test_read_state_returns_unknown_when_the_status_register_is_refused():
+    """A refused status read is "unknown", not an exception."""
+    vfd, _ = _connected([ExceptionResponse(function_code=3)])
+    assert asyncio.run(vfd.read_state()) is VFDState.UNKNOWN
 
 
 # -- state and faults -------------------------------------------------------

scietex_hal_vfd-2.0.2/tests/test_vesper_optional_reads.py

@@ -0,0 +1,176 @@
+"""
+Tests for the optional readings in the Vesper gateway clients.
+
+A poll loop publishes whatever `read_parameters` returns, so a drive that
+refuses one diagnostic register must still report its frequency, current and
+voltage. Only the measurement block is mandatory; the run state and the
+separate diagnostic registers degrade to ``None`` / ``VFDState.UNKNOWN``.
+
+The pymodbus client is replaced by a stub that returns canned responses, so
+these cover the degradation rules rather than the transport.
+"""
+
+import asyncio
+
+import pytest
+from pymodbus.pdu import ExceptionResponse
+from pymodbus.pdu.register_message import ReadHoldingRegistersResponse
+from scietex.hal.serial import ModbusOperationError
+
+from scietex.hal.vfd.base.data import VFDState
+from scietex.hal.vfd.vesper.e4_8400 import registers as e4_registers
+from scietex.hal.vfd.vesper.e4_8400.client import VesperE48400ModbusVFD
+from scietex.hal.vfd.vesper.e5_8200 import registers as e5_registers
+from scietex.hal.vfd.vesper.e5_8200.client import VesperE58200ModbusVFD
+
+#: E1-04 = 50.00 Hz, the factory maximum output frequency.
+E4_MAX_FREQUENCY_RAW = 5000
+
+
+class _StubClient:
+    """Stand-in for `AsyncModbusTcpClient` that replays canned responses."""
+
+    def __init__(self, responses):
+        self.responses = list(responses)
+        self.calls = []
+
+    async def read_holding_registers(self, address, *, count=1, device_id=1):
+        """Record the read and return the next canned response."""
+        self.calls.append(("read", address, count, device_id))
+        if not self.responses:
+            raise AssertionError("stub ran out of canned responses")
+        return self.responses.pop(0)
+
+
+def _read(values):
+    return ReadHoldingRegistersResponse(registers=list(values))
+
+
+def _refused():
+    return ExceptionResponse(function_code=3)
+
+
+def _e5(responses):
+    """Build an E5-8200 client whose stub replays ``responses``."""
+    vfd = VesperE58200ModbusVFD("127.0.0.1")
+    vfd._client = _StubClient(responses)
+    return vfd
+
+
+def _e4(responses):
+    """Build an E4-8400 client with E1-04 pre-supplied, so no extra read is queued."""
+    vfd = VesperE48400ModbusVFD("127.0.0.1", max_frequency_hz=50.0)
+    vfd._client = _StubClient(responses)
+    return vfd
+
+
+# -- E5-8200 ----------------------------------------------------------------
+
+
+def test_e5_read_parameters_survives_an_unreadable_monitor_register():
+    """A refused monitor read keeps the measurements and reports an unknown state."""
+    vfd = _e5([_read([5000, 3800, 540, 105]), _refused()])
+    parameters = asyncio.run(vfd.read_parameters())
+    assert parameters.frequency_hz == pytest.approx(50.0)
+    assert parameters.output_voltage == pytest.approx(380.0)
+    assert parameters.dc_bus_voltage == pytest.approx(540.0)
+    assert parameters.output_current == pytest.approx(10.5)
+    assert parameters.state is VFDState.UNKNOWN
+
+
+def test_e5_read_parameters_still_raises_when_the_block_fails():
+    """The measurement block is mandatory: without it there is nothing to report."""
+    vfd = _e5([_refused()])
+    with pytest.raises(ModbusOperationError):
+        asyncio.run(vfd.read_parameters())
+
+
+def test_e5_read_state_returns_unknown_when_the_monitor_register_is_refused():
+    """A refused monitor read is "unknown", not an exception."""
+    vfd = _e5([_refused()])
+    assert asyncio.run(vfd.read_state()) is VFDState.UNKNOWN
+
+
+# -- E4-8400 ----------------------------------------------------------------
+
+
+def test_e4_read_parameters_survives_unreadable_diagnostics():
+    """Voltage, DC bus, temperature and state all degrade instead of raising."""
+    vfd = _e4(
+        [
+            _read([5000, 5000, 105, 0]),  # setpoint, output freq, current
+            _refused(),  # U1-06 output voltage
+            _refused(),  # U1-07 DC bus voltage
+            _refused(),  # U1-46 heatsink temperature
+            _refused(),  # status
+        ]
+    )
+    parameters = asyncio.run(vfd.read_parameters())
+    assert parameters.frequency_hz == pytest.approx(50.0)
+    assert parameters.output_current == pytest.approx(10.5)
+    assert parameters.output_voltage == pytest.approx(0.0)
+    assert parameters.dc_bus_voltage is None
+    assert parameters.heatsink_temperature_c is None
+    assert parameters.state is VFDState.UNKNOWN
+
+
+def test_e4_read_parameters_keeps_the_temperature_when_only_the_state_fails():
+    """One refused register must not blank the others."""
+    vfd = _e4(
+        [
+            _read([5000, 5000, 105, 0]),
+            _read([380]),  # U1-06 output voltage
+            _read([540]),  # U1-07 DC bus voltage
+            _read([42]),  # U1-46 heatsink temperature
+            _refused(),  # status
+        ]
+    )
+    parameters = asyncio.run(vfd.read_parameters())
+    assert parameters.output_voltage == pytest.approx(380.0)
+    assert parameters.dc_bus_voltage == pytest.approx(540.0)
+    assert parameters.heatsink_temperature_c == pytest.approx(42.0)
+    assert parameters.state is VFDState.UNKNOWN
+
+
+def test_e4_read_parameters_still_raises_when_the_block_fails():
+    """The measurement block is mandatory: without it there is nothing to report."""
+    vfd = _e4([_refused()])
+    with pytest.raises(ModbusOperationError):
+        asyncio.run(vfd.read_parameters())
+
+
+def test_e4_read_state_returns_unknown_when_the_status_register_is_refused():
+    """A refused status read is "unknown", not an exception."""
+    vfd = _e4([_refused()])
+    assert asyncio.run(vfd.read_state()) is VFDState.UNKNOWN
+
+
+def test_e4_read_parameters_reads_e1_04_when_no_maximum_is_supplied():
+    """Without a constructor maximum the drive's own E1-04 is read first."""
+    vfd = VesperE48400ModbusVFD("127.0.0.1")
+    vfd._client = _StubClient(
+        [
+            _read([E4_MAX_FREQUENCY_RAW]),  # E1-04
+            _read([5000, 2500, 105, 0]),  # setpoint, output freq, current
+            _read([380]),
+            _read([540]),
+            _read([42]),
+            _read([0b011]),  # running forward
+        ]
+    )
+    parameters = asyncio.run(vfd.read_parameters())
+    assert vfd._client.calls[0] == (
+        "read",
+        e4_registers.parameter_register(e4_registers.PARAM_MAX_FREQUENCY),
+        1,
+        1,
+    )
+    assert parameters.frequency_hz == pytest.approx(25.0)
+    assert parameters.frequency_percent == pytest.approx(50.0)
+    assert parameters.state is VFDState.RUNNING_FORWARD
+
+
+def test_e5_parameter_block_addresses_are_unchanged():
+    """Guard the block the optional-read refactor reads from."""
+    assert e5_registers.PARAMETERS_BLOCK_ADDRESS == e5_registers.REG_OUTPUT_FREQUENCY
+    assert e5_registers.PARAMETERS_BLOCK_COUNT == 4