pypsgctrl 0.1.1__py3-none-any.whl

pypsgctrl/__init__.py

@@ -0,0 +1,16 @@
+## @file
+# @brief Public exports for the PSG9080 driver.
+"""PSG9080 serial driver. Import public classes directly from pypsgctrl."""
+from .channel import Channel
+from .device import PSG9080
+from .enums import FrequencyUnit, Modulation, TriggerSource, Waveform
+from .errors import PSGError, PSGTimeoutError, ProtocolError
+from .registers import CHANNEL_REGISTERS, REGISTERS, Register
+from .transport import Transport
+
+__version__ = '0.1.1'
+__all__ = [
+    'PSG9080', 'Channel', 'Waveform', 'FrequencyUnit', 'Modulation',
+    'TriggerSource', 'PSGError', 'ProtocolError', 'PSGTimeoutError',
+    'Transport', 'Register', 'REGISTERS', 'CHANNEL_REGISTERS', '__version__',
+]

pypsgctrl/channel.py

@@ -0,0 +1,184 @@
+## @file
+# @brief Channel settings and frequency/output properties.
+from __future__ import annotations
+
+from .enums import FrequencyUnit
+from .errors import ProtocolError
+from .registers import CHANNEL_REGISTERS, Register, _reg, _encode, _decode
+
+def _parameter(name):
+    return property(lambda self: self.get(name), lambda self, value: self.set(name, value),
+                    doc=f'{name}: physical value; see CHANNEL_REGISTERS.')
+
+
+## @brief Parameters of one channel; use PSG9080.ch1, ch2, or channel().
+class Channel:
+    ## @brief Create a channel object; normally constructed by PSG9080.
+    # @param device Parent PSG9080 instance.
+    # @param number Channel number 1 or 2; this constructor does not validate it.
+    def __init__(self, device, number):
+        self.device, self.number = device, number
+
+    def _register(self, name):
+        reg = CHANNEL_REGISTERS[name]
+        return Register(reg.code + self.number - 1, reg.scale, reg.offset,
+                        reg.minimum, reg.maximum)
+
+    ## @brief Read a CHANNEL_REGISTERS parameter.
+    # @param name Channel parameter name; frequency/enabled are separate properties.
+    # @return Decimal in physical units.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    # @exception KeyError Unknown parameter name.
+    def get(self, name):
+        reg = self._register(name)
+        return _decode(reg, self.device.read_raw(reg.code))
+
+    ## @brief Write a channel parameter after validating its value.
+    # @param name CHANNEL_REGISTERS parameter name.
+    # @param value Number, Decimal, IntEnum, or numeric string in physical units.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    # @exception KeyError Unknown parameter name.
+    def set(self, name, value):
+        reg = self._register(name)
+        raw = _encode(reg, value)
+        if name == 'waveform' and not (0 <= int(raw) <= 21 or 101 <= int(raw) <= 199):
+            raise ValueError('Waveform must be 0..21 or 101..199')
+        self.device.write_raw(reg.code, raw)
+
+    ## @brief Select an arbitrary waveform by slot number.
+    # @param slot Integer in 1..99; sends waveform code 100 + slot.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    def set_arbitrary_waveform(self, slot):
+        raw = _encode(_reg(0, minimum=1, maximum=99), slot)
+        self.set('waveform', 100 + int(raw))
+
+    ## @brief Set frequency in Hz using the chosen display units.
+    # @param hz Nonnegative frequency in Hz; MAXF depends on the device.
+    # @param display_unit FrequencyUnit; mHz/uHz scaling follows the document and is not hardware-verified.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    def set_frequency(self, hz, *, display_unit=FrequencyUnit.HZ):
+        unit = FrequencyUnit(display_unit)
+        # 0..2 select display units; documented examples retain millihertz
+        # ticks. For mHz/uHz, the document shows ticks per selected unit.
+        scale = {0: 1000, 1: 1000, 2: 1000, 3: 1000000, 4: 1000000000}[unit]
+        self.device.write_raw(12 + self.number,
+                              _encode(_reg(0, scale=scale), hz), int(unit))
+
+    ## @brief Read/write frequency in Hz; property assignment selects FrequencyUnit.HZ.
+    # @return Decimal when reading.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    @property
+    def frequency(self):
+        fields = self.device.read_raw(12 + self.number)
+        if len(fields) != 2:
+            raise ProtocolError('Frequency response requires value and unit')
+        try:
+            unit = FrequencyUnit(int(fields[1]))
+        except ValueError as exc:
+            raise ProtocolError('Unknown frequency unit') from exc
+        scale = {0: 1000, 1: 1000, 2: 1000, 3: 1000000, 4: 1000000000}[unit]
+        return _decode(_reg(0, scale=scale), fields[:1])
+
+    ## @brief Read/write frequency in Hz; property assignment selects FrequencyUnit.HZ.
+    # @param hz When writing: nonnegative frequency in Hz.
+    # @return Decimal when reading.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    @frequency.setter
+    def frequency(self, hz):
+        self.set_frequency(hz)
+
+    ## @brief Read/write output state; writing preserves the other channel state.
+    # @return bool when reading.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    @property
+    def enabled(self):
+        return bool(self.device.get('outputs')[self.number - 1])
+
+    ## @brief Read/write output state; writing preserves the other channel state.
+    # @param value When writing: bool or 0/1.
+    # @return bool when reading.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    @enabled.setter
+    def enabled(self, value):
+        encoded = _encode(_reg(10, maximum=1), value)
+        with self.device._lock:
+            states = list(self.device.get('outputs'))
+            states[self.number - 1] = encoded
+            self.device.set('outputs', *states)
+
+
+    ## @brief Waveform code: 0..21 or 101..199; arbitrary waveform 01 has code 101.
+    # @return Decimal when reading.
+    # @exception ValueError Invalid value when writing.
+    waveform = _parameter("waveform")
+
+    ## @brief Amplitude in Vpp, 0.001 V step; maximum depends on the device.
+    # @return Decimal when reading.
+    # @exception ValueError Invalid value when writing.
+    amplitude = _parameter("amplitude")
+
+    ## @brief Offset in V, 0.01 V step; minimum -10 V.
+    # @return Decimal when reading.
+    # @exception ValueError Invalid value when writing.
+    offset = _parameter("offset")
+
+    ## @brief Duty cycle in percent, 0..100, 0.01% step.
+    # @return Decimal when reading.
+    # @exception ValueError Invalid value when writing.
+    duty = _parameter("duty")
+
+    ## @brief Phase in degrees, 0..359.99, 0.01 degree step.
+    # @return Decimal when reading.
+    # @exception ValueError Invalid value when writing.
+    phase = _parameter("phase")
+
+    ## @brief Internal modulation frequency in Hz, 0..1000000, 0.001 Hz step.
+    # @return Decimal when reading.
+    # @exception ValueError Invalid value when writing.
+    modulation_frequency = _parameter("modulation_frequency")
+
+    ## @brief AM depth in percent, 0..200, 0.1% step.
+    # @return Decimal when reading.
+    # @exception ValueError Invalid value when writing.
+    am_depth = _parameter("am_depth")
+
+    ## @brief FM deviation in Hz, 0.1 Hz step.
+    # @return Decimal when reading.
+    # @exception ValueError Invalid value when writing.
+    fm_deviation = _parameter("fm_deviation")
+
+    ## @brief FSK frequency in Hz, 0.1 Hz step.
+    # @return Decimal when reading.
+    # @exception ValueError Invalid value when writing.
+    fsk_frequency = _parameter("fsk_frequency")
+
+    ## @brief PM deviation in degrees, 0..359.9, 0.1 degree step.
+    # @return Decimal when reading.
+    # @exception ValueError Invalid value when writing.
+    pm_deviation = _parameter("pm_deviation")
+
+    ## @brief Pulse width in seconds, 0..0.4, 1 ns step.
+    # @return Decimal when reading.
+    # @exception ValueError Invalid value when writing.
+    pulse_width = _parameter("pulse_width")
+
+    ## @brief Pulse period in seconds, 0..4, 10 ns step.
+    # @return Decimal when reading.
+    # @exception ValueError Invalid value when writing.
+    pulse_period = _parameter("pulse_period")

pypsgctrl/device.py

@@ -0,0 +1,252 @@
+## @file
+# @brief Serial connection and general device settings.
+from __future__ import annotations
+
+import re
+import threading
+import time
+
+from .channel import Channel
+from .errors import PSGError, PSGTimeoutError, ProtocolError
+from .registers import REGISTERS, _reg, _decimal, _encode, _decode
+from .transport import Transport
+
+## @brief Synchronous PSG9080 connection; transactions are protected by RLock.
+class PSG9080:
+    """Synchronous, transaction-locked PSG9080 connection.
+
+    Injected transports are borrowed unless owns_transport=True. Serial ports
+    opened by connect() are owned. A timed-out connection should be reopened:
+    the wire protocol has no transaction identifiers.
+    """
+    ## @brief Create a driver using an injected transport.
+    # @param transport Transport object; read() must have a finite timeout.
+    # @param owns_transport Close the transport on close(); defaults to False.
+    # @param response_timeout Positive finite response deadline in seconds.
+    def __init__(self, transport: Transport, *, owns_transport=False, response_timeout=1.0):
+        if _decimal(response_timeout) <= 0:
+            raise ValueError("response_timeout must be positive")
+        self.response_timeout = float(response_timeout)
+        self.transport = transport
+        self._owns_transport = owns_transport
+        self._closed = False
+        self._lock = threading.RLock()
+        self.ch1 = Channel(self, 1)
+        self.ch2 = Channel(self, 2)
+
+    ## @brief Open a serial port at 115200 baud, 8-N-1, without flow control.
+    # @param port Serial port path or pyserial URL.
+    # @param timeout Positive finite read, write, and response timeout in seconds.
+    # @return PSG9080 owning the opened transport.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    @classmethod
+    def connect(cls, port: str, *, timeout: float = 1.0):
+        if timeout <= 0 or not _decimal(timeout).is_finite():
+            raise ValueError('timeout must be positive and finite')
+        import serial
+        return cls(serial.serial_for_url(port, baudrate=115200, bytesize=8,
+                   parity='N', stopbits=1, timeout=timeout, write_timeout=timeout),
+                   owns_transport=True, response_timeout=timeout)
+
+    ## @brief Close the driver and its owned transport; repeated calls are allowed.
+    def close(self):
+        with self._lock:
+            if not self._closed and self._owns_transport:
+                self.transport.close()
+            self._closed = True
+
+    ## @brief Enter the connection context.
+    # @return This PSG9080 instance.
+    def __enter__(self):
+        return self
+
+    ## @brief Close the connection when leaving the context.
+    # @param args Context manager exception information.
+    def __exit__(self, *args):
+        self.close()
+
+    ## @brief Get a channel object.
+    # @param number Channel number 1 or 2; bool is rejected.
+    # @return Channel.
+    def channel(self, number):
+        if isinstance(number, bool) or number not in (1, 2):
+            raise ValueError('Channel must be 1 or 2')
+        return self.ch1 if number == 1 else self.ch2
+
+    def _exchange(self, operator, code, payload):
+        if type(code) is not int or not 0 <= code <= 99:
+            raise ValueError('Function code must be an integer in [0, 99]')
+        if not re.fullmatch(r'[0-9a-fA-F,+-]+', payload):
+            raise ValueError('Invalid raw payload')
+        command = f':{operator}{code}={payload}.\r\n'.encode('ascii')
+        with self._lock:
+            if self._closed:
+                raise PSGError('Connection is closed')
+            if self.transport.write(command) != len(command):
+                raise ProtocolError('Incomplete transport write')
+            deadline = time.monotonic() + self.response_timeout
+            response = bytearray()
+            while not response.endswith(b'\r\n'):
+                if time.monotonic() >= deadline:
+                    raise PSGTimeoutError("Response deadline exceeded; reopen connection")
+                part = self.transport.read(1)
+                if not part:
+                    raise PSGTimeoutError('Timed out waiting for CRLF response; reopen connection')
+                response.extend(part)
+                if len(response) > 65536:
+                    raise ProtocolError('Response exceeds 65536 bytes')
+            try:
+                line = bytes(response[:-2]).decode('ascii')
+            except UnicodeDecodeError as exc:
+                raise ProtocolError('Response is not ASCII') from exc
+            if operator == 'w':
+                if line not in ('OK', 'OK.', ':ok'):
+                    raise ProtocolError(f'Write rejected: {line!r}')
+                return ()
+            match = re.fullmatch(r':r(\d{1,2})=([^\r\n]+)\.', line)
+            if not match or int(match[1]) != code:
+                raise ProtocolError(f'Unexpected read response: {line!r}')
+            return tuple(match[2].split(','))
+
+    ## @brief Read raw fields using :rCODE=0. followed by CRLF.
+    # @param code Integer function code in 0..99.
+    # @return tuple[str, ...] without unit conversion.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    def read_raw(self, code):
+        """Return unscaled ASCII fields from :rCODE=0. command."""
+        return self._exchange('r', code, '0')
+
+    ## @brief Write raw ASCII fields and verify an OK, OK., or :ok acknowledgment.
+    # @param code Integer function code in 0..99.
+    # @param fields Fields without a terminator or CRLF; hexadecimal selectors are supported.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    def write_raw(self, code, *fields):
+        """Write literal fields, including hexadecimal interface selectors."""
+        self._exchange('w', code, ','.join(str(f) for f in fields))
+
+    ## @brief Read a general parameter from REGISTERS.
+    # @param name General register name.
+    # @return Decimal or tuple[Decimal, ...]; interface returns tuple[int, ...].
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    # @exception KeyError Unknown parameter name.
+    def get(self, name):
+        reg = REGISTERS[name]
+        fields = self.read_raw(reg.code)
+        if name == 'interface':
+            if len(fields) != 4 or any(not re.fullmatch('[0-9a-fA-F]{1,2}', f) for f in fields):
+                raise ProtocolError('Invalid interface selector')
+            return tuple(int(f, 16) for f in fields)
+        if name == 'sync' and len(fields) == 1 and re.fullmatch('[01]{6}', fields[0]):
+            fields = tuple(fields[0])
+        return _decode(reg, fields)
+
+    ## @brief Write a general parameter after validating its range and resolution.
+    # @param name Writable general register name.
+    # @param values Physical values in register field order.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    # @exception KeyError Unknown parameter name.
+    def set(self, name, *values):
+        reg = REGISTERS[name]
+        if not reg.writable or name == 'memory':
+            raise ValueError('Use memory methods, or register is read-only')
+        if len(values) != reg.count:
+            raise ValueError(f'{name} requires {reg.count} values')
+        if name == 'interface':
+            encoded = [_encode(_reg(24, maximum=255), v) for v in values]
+            self.write_raw(reg.code, *(format(int(v), 'x') for v in encoded))
+        else:
+            self.write_raw(reg.code, *(_encode(reg, v) for v in values))
+
+    ## @brief Set both output states.
+    # @param ch1 True/1 enables CH1; False/0 disables it.
+    # @param ch2 True/1 enables CH2; False/0 disables it.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    def set_outputs(self, ch1: bool, ch2: bool):
+        self.set('outputs', ch1, ch2)
+
+    ## @brief Configure synchronization with CH1 as the leader.
+    # @param waveform Synchronization flag for waveform.
+    # @param frequency Synchronization flag for frequency.
+    # @param amplitude Synchronization flag for amplitude.
+    # @param offset Synchronization flag for offset.
+    # @param duty Synchronization flag for duty.
+    # @param external Synchronization flag for external.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    def set_sync(self, *, waveform=False, frequency=False, amplitude=False,
+                 offset=False, duty=False, external=False):
+        self.set('sync', waveform, frequency, amplitude, offset, duty, external)
+
+    def _memory(self, slot, operation):
+        self.write_raw(26, _encode(_reg(26), slot), operation)
+
+    ## @brief Load parameters from memory using command 26/111.
+    # @param slot Nonnegative integer memory slot; the upper limit is undocumented.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    def load(self, slot):
+        self._memory(slot, 111)
+
+    ## @brief Save parameters to memory using command 26/222.
+    # @param slot Nonnegative integer memory slot.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    def save(self, slot):
+        self._memory(slot, 222)
+
+    ## @brief Clear one memory slot using command 26/333.
+    # @param slot Nonnegative integer memory slot.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    def clear(self, slot):
+        self._memory(slot, 333)
+
+    ## @brief Clear all memory slots using command 26/444.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    def clear_all(self):
+        self._memory(0, 444)
+
+    ## @brief Configure measurement using command 62; does not start measurement.
+    # @param dc False: AC; True: DC coupling at Ext.IN.
+    # @param gate_seconds Gate time in 0.001..10 seconds, with a 0.001 s step.
+    # @param low_frequency False: high-frequency mode; True: low-frequency mode.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    def configure_measurement(self, *, dc=False, gate_seconds='0.02', low_frequency=False):
+        self.write_raw(62, _encode(_reg(62, maximum=1), dc),
+                       _encode(_reg(62, scale=1000, minimum='0.001', maximum=10), gate_seconds),
+                       _encode(_reg(62, maximum=1), low_frequency))
+
+    ## @brief Configure sweep using command 64; does not enable sweep.
+    # @param channel Channel 1 or 2.
+    # @param seconds Time in 0.01..640 seconds, with a 0.01 s step.
+    # @param direction 0: increasing; 1: decreasing; 2: back and forth.
+    # @param logarithmic False: linear sweep; True: logarithmic sweep.
+    # @exception PSGTimeoutError Incomplete response or expired timeout.
+    # @exception ProtocolError Unexpected device response.
+    # @exception ValueError Invalid input value.
+    def configure_sweep(self, *, channel=1, seconds=10, direction=0, logarithmic=False):
+        self.channel(channel)
+        self.write_raw(64, channel - 1,
+                       _encode(_reg(64, scale=100, minimum='0.01', maximum=640), seconds),
+                       _encode(_reg(64, maximum=2), direction),
+                       _encode(_reg(64, maximum=1), logarithmic))

pypsgctrl/enums.py

@@ -0,0 +1,60 @@
+## @file
+# @brief Protocol enumerations.
+from __future__ import annotations
+
+from enum import IntEnum
+
+## @brief Built-in waveform codes; arbitrary waveforms use slots 1..99.
+class Waveform(IntEnum):
+    SINE = 0
+    SQUARE = 1
+    PULSE = 2
+    TRIANGLE = 3
+    SLOPE = 4
+    CMOS = 5
+    DC = 6
+    PARTIAL_SINE = 7
+    HALF_WAVE = 8
+    FULL_WAVE = 9
+    POSITIVE_LADDER = 10
+    NEGATIVE_LADDER = 11
+    POSITIVE_TRAPEZOID = 12
+    NEGATIVE_TRAPEZOID = 13
+    NOISE = 14
+    EXPONENTIAL_RISE = 15
+    EXPONENTIAL_FALL = 16
+    LOGARITHMIC_RISE = 17
+    LOGARITHMIC_FALL = 18
+    SINKER_PULSE = 19
+    MULTI_AUDIO = 20
+    LORENZ = 21
+
+
+## @brief Frequency display unit codes. API frequencies are always in Hz.
+class FrequencyUnit(IntEnum):
+    HZ = 0
+    KHZ = 1
+    MHZ = 2
+    MILLIHZ = 3
+    MHZ_SMALL = 3  # compatibility alias for millihertz
+    UHZ = 4
+
+
+## @brief Modulation type codes for the two channels.
+class Modulation(IntEnum):
+    AM = 0
+    FM = 1
+    PM = 2
+    ASK = 3
+    FSK = 4
+    PSK = 5
+    PULSE = 6
+    BURST = 7
+
+
+## @brief Trigger sources: key, internal, external AC, or external DC.
+class TriggerSource(IntEnum):
+    KEY = 0
+    INTERNAL = 1
+    EXTERNAL_AC = 2
+    EXTERNAL_DC = 3

pypsgctrl/errors.py

@@ -0,0 +1,17 @@
+## @file
+# @brief Driver exceptions.
+from __future__ import annotations
+
+## @brief Base driver exception.
+class PSGError(Exception):
+    """Base driver error."""
+
+
+## @brief Malformed response, rejected write, or incomplete write.
+class ProtocolError(PSGError):
+    """Malformed, unexpected, or rejected device response."""
+
+
+## @brief Response timeout expired; reopen the connection.
+class PSGTimeoutError(PSGError, TimeoutError):
+    """No complete response arrived within the transport timeout."""

pypsgctrl/registers.py

@@ -0,0 +1,121 @@
+## @file
+# @brief Register metadata and physical-value conversion.
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Decimal, InvalidOperation
+from enum import IntEnum
+import re
+
+from .errors import ProtocolError
+
+## @brief Immutable register descriptor: raw = value * scale + offset.
+@dataclass(frozen=True)
+class Register:
+    ## @brief Protocol function code.
+    code: int
+    ## @brief Wire ticks per physical unit.
+    scale: Decimal = Decimal(1)
+    ## @brief Additive wire-value offset.
+    offset: Decimal = Decimal(0)
+    ## @brief Minimum physical value, or None for no lower bound.
+    minimum: Decimal | None = Decimal(0)
+    ## @brief Maximum physical value, or None for no upper bound.
+    maximum: Decimal | None = None
+    ## @brief Number of fields in a response or command.
+    count: int = 1
+    ## @brief Whether the general API permits writing this register.
+    writable: bool = True
+
+
+def _reg(code, scale=1, offset=0, minimum=0, maximum=None, count=1, writable=True):
+    return Register(code, Decimal(str(scale)), Decimal(str(offset)),
+                    None if minimum is None else Decimal(str(minimum)),
+                    None if maximum is None else Decimal(str(maximum)), count, writable)
+
+
+# scale is wire ticks per physical unit. Times are seconds, voltages Vpp/V,
+# angles degrees, duty/depth percent, and frequencies Hz.
+## @brief General register catalog; field order is documented in api_reference_en.md.
+REGISTERS = {
+    'outputs': _reg(10, maximum=1, count=2),
+    'interface': _reg(24, count=4),
+    'sync': _reg(25, maximum=1, count=6),
+    'memory': _reg(26),
+    'sound': _reg(27, maximum=1),
+    'brightness': _reg(28, maximum=100),
+    'language': _reg(29, maximum=1),
+    'preset_wave_count': _reg(30, maximum=39),
+    'arbitrary_wave_count': _reg(31, maximum=99),
+    'wave_loading': _reg(32, maximum=1),
+    'frequency_trim': _reg(33, minimum=None),
+    'modulation': _reg(40, maximum=7, count=2),
+    'modulation_waveform': _reg(41, maximum=9, count=2),
+    'modulation_source': _reg(42, maximum=1, count=2),
+    'pulse_inversion': _reg(57, maximum=1, count=2),
+    'burst_idle': _reg(58, maximum=2, count=2),
+    'polarity': _reg(59, maximum=1, count=2),
+    'trigger_source': _reg(60, maximum=3, count=2),
+    'burst_count': _reg(61, maximum=1000000000, count=2),
+    'measurement_mode': _reg(63, maximum=1),
+    'sweep_enabled': _reg(65, maximum=1, count=2),
+    'sweep_start_frequency': _reg(66, scale=10),
+    'sweep_end_frequency': _reg(67, scale=10),
+    'sweep_start_amplitude': _reg(68, scale=1000),
+    'sweep_end_amplitude': _reg(69, scale=1000),
+    'sweep_start_duty': _reg(70, scale=100, maximum=100),
+    'sweep_end_duty': _reg(71, scale=100, maximum=100),
+    'voltage_calibration_min': _reg(72),
+    'voltage_calibration_max': _reg(73),
+    'trigger': _reg(74, maximum=1, count=2),
+    'counter': _reg(80, writable=False),
+    'measured_high_frequency': _reg(81, writable=False),
+    'measured_low_frequency': _reg(82, scale=1000, writable=False),
+    'measured_positive_width': _reg(83, scale=1000000000, writable=False),
+    'measured_negative_width': _reg(84, scale=1000000000, writable=False),
+    'measured_period': _reg(85, scale=100000000, writable=False),
+    'measured_duty': _reg(86, scale=100, maximum=100, writable=False),
+}
+## @brief Channel register catalog: CH2 code equals CH1 code + 1.
+CHANNEL_REGISTERS = {
+    'waveform': _reg(11, maximum=199),
+    'amplitude': _reg(15, scale=1000),
+    'offset': _reg(17, scale=100, offset=1000, minimum=-10),
+    'duty': _reg(19, scale=100, maximum=100),
+    'phase': _reg(21, scale=100, maximum='359.99'),
+    'modulation_frequency': _reg(43, scale=1000, maximum=1000000),
+    'am_depth': _reg(45, scale=10, maximum=200),
+    'fm_deviation': _reg(47, scale=10),
+    'fsk_frequency': _reg(49, scale=10),
+    'pm_deviation': _reg(51, scale=10, maximum='359.9'),
+    'pulse_width': _reg(53, scale=1000000000, maximum='0.4'),
+    'pulse_period': _reg(55, scale=100000000, maximum=4),
+}
+
+
+def _decimal(value):
+    try:
+        d = Decimal(int(value)) if isinstance(value, (bool, IntEnum)) else Decimal(str(value))
+    except (InvalidOperation, ValueError, TypeError) as exc:
+        raise ValueError('Expected a finite numeric value') from exc
+    if not d.is_finite():
+        raise ValueError('Expected a finite numeric value')
+    return d
+
+
+def _encode(reg, value):
+    d = _decimal(value)
+    if ((reg.minimum is not None and d < reg.minimum) or
+            (reg.maximum is not None and d > reg.maximum)):
+        raise ValueError(f'Value outside range [{reg.minimum}, {reg.maximum}]')
+    raw = d * reg.scale + reg.offset
+    if raw != raw.to_integral_value():
+        raise ValueError(f'Value must be a multiple of {1 / reg.scale}')
+    return str(int(raw))
+
+
+def _decode(reg, fields):
+    if len(fields) != reg.count or any(not re.fullmatch(r'-?\d+', f) for f in fields):
+        raise ProtocolError(f'Invalid payload for register {reg.code}: {fields!r}')
+    values = tuple((Decimal(f) - reg.offset) / reg.scale for f in fields)
+    return values[0] if reg.count == 1 else values

pypsgctrl/transport.py

@@ -0,0 +1,18 @@
+## @file
+# @brief Injected transport interface.
+from __future__ import annotations
+
+from typing import Protocol
+
+## @brief Transport contract requiring a finite read timeout.
+class Transport(Protocol):
+    ## @brief Write command bytes.
+    # @param data ASCII command terminated with CRLF.
+    # @return Number of bytes actually written.
+    def write(self, data: bytes) -> int: ...
+    ## @brief Read up to size bytes with a finite timeout.
+    # @param size Requested byte count.
+    # @return bytes; empty bytes indicate a timeout.
+    def read(self, size: int = 1) -> bytes: ...
+    ## @brief Close transport resources.
+    def close(self) -> None: ...

pypsgctrl-0.1.1.dist-info/METADATA

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: pypsgctrl
+Version: 0.1.1
+Summary: Python driver for the PSG9080 dual-channel function generator with USB serial control.
+Author: Oleg Kochetov
+License-Expression: MIT
+Project-URL: Repository, https://github.com/realspinner/pypsgctrl
+Project-URL: Documentation, https://github.com/realspinner/pypsgctrl/blob/main/docs/api_reference_en.md
+Project-URL: Issues, https://github.com/realspinner/pypsgctrl/issues
+Keywords: PSG9080,function-generator,serial,instrument-control
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial>=3.5
+Dynamic: license-file
+
+# pypsgctrl
+
+English documentation is followed by the Russian translation.
+После английского текста приведена русская версия.
+
+## English
+
+A synchronous Python driver for the PSG9080 dual-channel function generator over
+USB serial. Supports waveforms, frequency, amplitude, offset, duty cycle, phase,
+modulation, measurement, sweep, system settings, and parameter memory.
+
+### Installation
+
+Python 3.10 or newer is required. pyserial is installed automatically.
+
+For releases published on PyPI:
+
+```sh
+python -m pip install pypsgctrl
+```
+
+The package is available on TestPyPI; production publication is pending.
+Until then, install directly from GitHub:
+
+```sh
+python -m pip install "git+https://github.com/realspinner/pypsgctrl.git"
+```
+
+To install this release from TestPyPI in a fresh virtual environment:
+
+```sh
+python -m pip install pyserial
+python -m pip install --index-url https://test.pypi.org/simple/ --no-deps pypsgctrl==0.1.1
+```
+
+After cloning the repository, use `python -m pip install -e .` for development. Serial settings: 115200 baud,
+8-N-1, without flow control. Replace the macOS example port with your device's port.
+Opening a connection does not enable outputs.
+
+### Quick start
+
+```python
+from pypsgctrl import PSG9080, Waveform
+
+with PSG9080.connect('/dev/cu.usbserial-2120', timeout=1.0) as generator:
+    print(generator.ch1.frequency)       # Decimal, Hz
+    generator.ch1.waveform = Waveform.SINE
+    generator.ch1.frequency = 1000
+    generator.ch1.amplitude = '0.100'    # Vpp, not RMS
+    generator.ch1.offset = 0            # V
+    generator.set_outputs(True, False)
+```
+
+Writes take effect immediately. Physical readbacks use Decimal; numeric strings
+and Decimal support exact fractions. Values between device steps are rejected.
+Transactions are serialized with an instance lock. After a timeout, close and
+reopen the connection. Hardware limits absent from the protocol remain the caller's responsibility.
+
+### Documentation and structure
+
+[English API reference](https://github.com/realspinner/pypsgctrl/blob/main/docs/api_reference_en.md) · [Russian API reference](https://github.com/realspinner/pypsgctrl/blob/main/docs/api_reference_ru.md)
+
+| Module | Purpose |
+| --- | --- |
+| `pypsgctrl/__init__.py` | Stable public imports and version |
+| `pypsgctrl/device.py` | Connection, wire exchange, general settings |
+| `pypsgctrl/channel.py` | Channel properties, frequency/output control |
+| `pypsgctrl/registers.py` | Register metadata and unit conversion |
+| `pypsgctrl/enums.py` | Waveform, frequency, modulation, trigger enums |
+| `pypsgctrl/errors.py` | Driver exceptions |
+| `pypsgctrl/transport.py` | Injectable transport contract |
+
+Public imports use `from pypsgctrl import PSG9080, Waveform`.
+Report bugs through [GitHub Issues](https://github.com/realspinner/pypsgctrl/issues). Source comments use Doxygen
+tags. With Doxygen installed, run `doxygen Doxyfile` from the repository root to generate
+`build/doxygen/html`.
+
+### License
+
+MIT License, copyright 2026 Oleg Kochetov. See [LICENSE](https://github.com/realspinner/pypsgctrl/blob/main/LICENSE).
+Vendor PDFs and recorder calibration utilities are not included in this repository.
+
+## Русский
+
+Синхронный Python-драйвер двухканального генератора PSG9080 по USB serial.
+Поддерживает форму, частоту, амплитуду, смещение, duty, фазу, модуляцию,
+измерение, sweep, системные настройки и память параметров.
+
+### Установка
+
+Требуется Python 3.10 или новее. pyserial устанавливается автоматически.
+
+Для релизов, опубликованных на основном PyPI:
+
+```sh
+python -m pip install pypsgctrl
+```
+
+Пакет доступен на TestPyPI; публикация на основном PyPI ещё не выполнена.
+До неё можно установить пакет из GitHub:
+
+```sh
+python -m pip install "git+https://github.com/realspinner/pypsgctrl.git"
+```
+
+Установка этой версии с TestPyPI в новом виртуальном окружении:
+
+```sh
+python -m pip install pyserial
+python -m pip install --index-url https://test.pypi.org/simple/ --no-deps pypsgctrl==0.1.1
+```
+
+После клонирования для разработки: `python -m pip install -e .`. Порт: 115200 baud, 8-N-1,
+без flow control. Замените пример macOS на свой порт. Подключение не включает выходы.
+
+### Быстрый старт
+
+```python
+from pypsgctrl import PSG9080, Waveform
+
+with PSG9080.connect('/dev/cu.usbserial-2120', timeout=1.0) as generator:
+    print(generator.ch1.frequency)       # Decimal, Hz
+    generator.ch1.waveform = Waveform.SINE
+    generator.ch1.frequency = 1000
+    generator.ch1.amplitude = '0.100'    # Vpp, not RMS
+    generator.ch1.offset = 0            # V
+    generator.set_outputs(True, False)
+```
+
+Записи применяются немедленно. Физические значения возвращаются как Decimal;
+строки и Decimal позволяют задать точные дроби. Значения между шагами отвергаются.
+Обмен защищён блокировкой экземпляра. После таймаута соединение следует открыть
+заново. Неописанные в протоколе аппаратные пределы учитывает вызывающий код.
+
+### Документация и структура
+
+[Справочник на английском](https://github.com/realspinner/pypsgctrl/blob/main/docs/api_reference_en.md) · [Справочник на русском](https://github.com/realspinner/pypsgctrl/blob/main/docs/api_reference_ru.md)
+
+| Модуль | Назначение |
+| --- | --- |
+| `pypsgctrl/__init__.py` | Стабильные публичные импорты и версия |
+| `pypsgctrl/device.py` | Соединение, обмен, общие настройки |
+| `pypsgctrl/channel.py` | Свойства канала, частота и управление выходом |
+| `pypsgctrl/registers.py` | Метаданные регистров и преобразование единиц |
+| `pypsgctrl/enums.py` | Перечисления формы, частоты, модуляции и запуска |
+| `pypsgctrl/errors.py` | Исключения драйвера |
+| `pypsgctrl/transport.py` | Контракт внедряемого транспорта |
+
+Публичные импорты: `from pypsgctrl import PSG9080, Waveform`.
+Об ошибках можно сообщить через [GitHub Issues](https://github.com/realspinner/pypsgctrl/issues). Комментарии оформлены
+тегами Doxygen. При установленном Doxygen команда `doxygen Doxyfile` из корня репозитория
+генерирует `build/doxygen/html`.
+
+### Лицензия
+
+MIT License, правообладатель — Oleg Kochetov, 2026. См. [LICENSE](https://github.com/realspinner/pypsgctrl/blob/main/LICENSE).
+PDF производителя и утилиты калибровки рекордера в репозиторий не включены.

pypsgctrl-0.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+pypsgctrl/__init__.py,sha256=s3QGiDmfm6eor_QaAwE6_ZZ1fzjaSSlvSelK7Z2nnRQ,669
+pypsgctrl/channel.py,sha256=wKzM8MJ0GjKJdphCtgQzAtDO5CrQs82CYY7MYfZLjGo,8259
+pypsgctrl/device.py,sha256=Dnk9nsoAbji9g0bP4w3sAwKLnGJKfzaE5BdsJCfNSKs,12467
+pypsgctrl/enums.py,sha256=mNwRtALvujtQsS1ip77FZlyP-g6kFoMk-JcILuYtu50,1215
+pypsgctrl/errors.py,sha256=9Xd8Aozv1WfmyiV-2Qv5oCXmO8Fbg6TsXiJaityfL0w,501
+pypsgctrl/registers.py,sha256=_Y1Ajj_xJOOyw3MyGyjng-zdwEwC3mUH6QMwdugCS8c,5150
+pypsgctrl/transport.py,sha256=2jUCM33wOzocRtZo2PcRL1uJyljrYzBFDcv1I4hBhio,658
+pypsgctrl-0.1.1.dist-info/licenses/LICENSE,sha256=ser5brmfUMyLrjLL3PC9egkI4kN-qMEi6eQkBbkfJ7g,1070
+pypsgctrl-0.1.1.dist-info/METADATA,sha256=IVwLdu0Jz25AsP27Db1UpgBPB2H_vhJVh1DQCxVlvBY,8274
+pypsgctrl-0.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pypsgctrl-0.1.1.dist-info/top_level.txt,sha256=N-BDXO0PlibGCG7F6tGDBtRPEsRLPrVK7B1xHd_v1To,10
+pypsgctrl-0.1.1.dist-info/RECORD,,

pypsgctrl-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pypsgctrl-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleg Kochetov
+
+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.

pypsgctrl-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+pypsgctrl