ldcon 0.2.0__py3-none-any.whl

ldcon/drivers/cld1015.py

@@ -0,0 +1,296 @@
+"""CLD1015 DOC-104674 Rev B, pp40-44: direct USBTMC/VISA, no DLL required."""
+import math
+import os
+import hashlib
+import threading
+import time
+from ldcon.drivers.cld1015_config import check
+from ldcon.core.device_conditions import TemperatureConditions
+
+
+class InvalidMeasurement(RuntimeError):
+    """Invalid numeric evidence; the caller must still track any prior write."""
+
+
+class PhysicalLock:
+    """Keep the legacy resource flock while an owner replaces a read session."""
+    def __init__(self, resource):
+        if not resource or resource == "auto":
+            raise ValueError("Physical ownership requires a pinned VISA resource")
+        from ldcon.owners.migration_physical_lock import acquire_visa
+        self.resource = resource
+        self.handle = acquire_visa(resource)
+
+    def check(self, resource):
+        if self.handle.closed or self.resource != resource:
+            raise ValueError("Physical lock does not own the requested VISA resource")
+
+    def close(self):
+        self.handle.close()
+
+
+class VisaIO:
+    def __init__(self, resource, timeout_s, *, physical_lock=None):
+        import pyvisa
+        self.rm = pyvisa.ResourceManager()
+        self.inst = None
+        self.process_lock = None
+        try:
+            if resource in (None, "auto"):
+                candidates = []
+                for address in self.rm.list_resources("USB?*::INSTR"):
+                    try:
+                        if int(address.split("::")[1], 0) == 0x1313:
+                            candidates.append(address)
+                    except (ValueError, IndexError):
+                        continue
+                if len(candidates) != 1:
+                    raise ValueError(f"Expected one Thorlabs USB VISA device, found {len(candidates)}; check USB/driver or specify resource")
+                resource = candidates[0]
+            if physical_lock is not None:
+                if not isinstance(physical_lock, PhysicalLock):
+                    raise ValueError("Expected a held CLD1015 PhysicalLock")
+                physical_lock.check(resource)
+            elif os.name == "posix":
+                self.process_lock = PhysicalLock(resource)
+            self.inst = self.rm.open_resource(resource)
+            self.inst.timeout = int(timeout_s * 1000)
+            self.inst.read_termination = self.inst.write_termination = "\n"
+            try:
+                self.inst.lock_excl(timeout=int(timeout_s * 1000))
+            except NotImplementedError:
+                if self.process_lock is None and physical_lock is None:
+                    raise
+            except pyvisa.errors.VisaIOError as exc:
+                if (self.process_lock is None and physical_lock is None) or exc.error_code != pyvisa.constants.StatusCode.error_nonsupported_operation:
+                    raise
+        except Exception:
+            self.close()
+            raise
+
+    def query(self, command):
+        return self.inst.query(command).strip()
+
+    def write(self, command):
+        self.inst.write(command)
+
+    def close(self):
+        if self.inst is not None:
+            self.inst.close()
+        self.rm.close()
+        if self.process_lock is not None:
+            self.process_lock.close()
+            self.process_lock = None
+
+
+class Controller:
+    def __init__(self, config, factory=None):
+        self.config, self.factory = config, factory
+        self.io = None
+        self.lock = threading.RLock()
+
+    def connect(self):
+        with self.lock:
+            if self.io is None:
+                self.io = (self.factory() if self.factory else MockIO() if self.config["mock"] else
+                           VisaIO(self.config["resource"], self.config["timeout_s"]))
+                try:
+                    if "CLD1015" not in self.io.query("*IDN?").upper():
+                        raise RuntimeError("USB instrument is not a CLD1015")
+                except Exception:
+                    self.close()
+                    raise
+            return self.read()
+
+    def close(self):
+        with self.lock:
+            if self.io is not None:
+                self.io.close()
+                self.io = None
+
+    def query(self, command):
+        if self.io is None:
+            raise RuntimeError("Connect to CLD1015 first")
+        return self.io.query(command).strip()
+
+    def command(self, command):
+        self.io.write(command)
+        if self.query("*OPC?") != "1":
+            raise RuntimeError("CLD1015 command did not complete")
+        error = self.query("SYST:ERR?")
+        if int(error.split(",", 1)[0]) != 0:
+            raise RuntimeError(f"CLD1015: {error}")
+
+    def _unit(self):
+        unit = self.query("UNIT:TEMP?").upper()
+        if unit in ("C", "CEL", "CELSIUS"):
+            return 1., 0.
+        if unit in ("K", "KEL", "KELVIN"):
+            return 1., -273.15
+        if unit in ("F", "FAR", "FAHR", "FAHRENHEIT"):
+            return 5 / 9, -160 / 9
+        raise ValueError(f"Unknown CLD1015 temperature unit: {unit}")
+
+    def read(self):
+        with self.lock:
+            scale, offset = self._unit()
+            def number(cmd, field):
+                raw = self.query(cmd)
+                try:
+                    value = float(raw)
+                except (ValueError, TypeError, OverflowError) as exc:
+                    raise InvalidMeasurement(f"Invalid CLD1015 {field} ({cmd}): {raw!r}") from exc
+                if not math.isfinite(value):
+                    raise InvalidMeasurement(f"Nonfinite CLD1015 {field} ({cmd}): {raw!r}")
+                return value
+            enabled = lambda cmd: self.query(cmd).upper() in ("1", "1.0", "ON")
+            data = dict(current_a=number("SOUR1:CURR?", "current_a"), current_read_a=number("SENS3:CURR:DATA?", "current_read_a"),
+                        temperature_c=number("SOUR2:TEMP:SPO?", "temperature_c") * scale + offset,
+                        temperature_read_c=number("SENS2:TEMP:DATA?", "temperature_read_c") * scale + offset,
+                        tec_current_a=number("SOUR2:CURR:DATA?", "tec_current_a"),
+                        current_limit_a=number("SOUR1:CURR:LIM?", "current_limit_a"),
+                        ld_enabled=enabled("OUTP1?"),
+                        tec_enabled=enabled("OUTP2?"),
+                        modulation_enabled=enabled("SOUR1:AM:STAT?"),
+                        ld_mode=self.query("SOUR1:FUNC:MODE?"), tec_mode=self.query("SOUR2:FUNC:MODE?"))
+            invalid = [key for key, value in data.items() if isinstance(value, float) and not math.isfinite(value)]
+            if invalid:
+                raise InvalidMeasurement("Nonfinite converted CLD1015 fields: " + ", ".join(invalid))
+            return data
+
+    def validate(self, request):
+        if not request or set(request) - {"current_a", "temperature_c"}:
+            raise ValueError("Setpoints must contain current_a and/or temperature_c only")
+        state = self.read()
+        if "current_a" in request:
+            value = check(request["current_a"], self.config["current_limits_a"], "current")
+            if state["ld_mode"].upper() not in ("CURR", "CURRENT"):
+                raise ValueError("LD must already be in constant-current mode")
+            if not 0 <= value <= state["current_limit_a"]:
+                raise ValueError("Requested current exceeds controller current limit")
+        if "temperature_c" in request:
+            value = check(request["temperature_c"], self.config["temperature_limits_c"], "temperature")
+            if state["tec_mode"].upper() not in ("TEMP", "TEMPERATURE"):
+                raise ValueError("TEC must already be in temperature mode")
+            scale, offset = self._unit()
+            lo = float(self.query("SOUR2:TEMP:LIM:LOW?")) * scale + offset
+            hi = float(self.query("SOUR2:TEMP:LIM:UPP?")) * scale + offset
+            if not lo <= value <= hi:
+                raise ValueError("Temperature exceeds controller temperature limits")
+        return state
+
+    def apply(self, request, *, ramp_s=0):
+        with self.lock:
+            if not self.config.get('temperature_writes_enabled',True):raise ValueError('Laser output writes are not enabled')
+            if self.config.get('current_conditions') is not None and 'current_a' in request:
+                from ldcon.owners.current_owner import apply_current
+                return apply_current(self,request,ramp_s)
+            before = self.validate(request)  # Validate the whole request before writing.
+            ramp_s = float(ramp_s)
+            if not math.isfinite(ramp_s) or not 0 <= ramp_s <= 3600:
+                raise ValueError("ramp_s must be finite in 0..3600 s")
+            policy = self.config.get('temperature_conditions')
+            guard = TemperatureConditions(policy,self.config.get('control_settings')) if policy is not None and 'temperature_c' in request else None
+            delta_temperature = abs(float(request.get('temperature_c', before['temperature_c']))-before['temperature_c'])
+            if guard and not guard.low<=float(request['temperature_c'])<=guard.high:
+                raise ValueError('Final temperature exceeds absolute device envelope')
+            if guard and delta_temperature and ramp_s<=0:
+                raise ValueError('Temperature device policy requires a timed ramp')
+            steps = max(1, math.ceil(ramp_s / .1))
+            if guard:
+                steps=max(1,math.ceil(ramp_s/.5),math.ceil(max(0.,delta_temperature-1e-12)/guard.step))
+                interval=self.config.get('control_settings',{}).get('temperature',{}).get('output_update_interval_s')
+                if interval is not None:
+                    interval=float(interval)
+                    if not math.isfinite(interval) or not .1<=interval<=2:raise ValueError('Invalid device temperature update interval')
+                    steps=max(1,math.ceil(max(0.,delta_temperature-1e-12)/guard.step))
+                    if ramp_s+1e-9<steps*interval:raise ValueError('Temperature ramp is faster than device update interval')
+            scale, offset = self._unit()
+            previous_temperature=before['temperature_c'];previous_time=time.monotonic()
+            for step in range(1, steps + 1):
+                if ramp_s:time.sleep(ramp_s/steps)
+                candidate=before['temperature_c']+(float(request.get('temperature_c',before['temperature_c']))-before['temperature_c'])*step/steps
+                if guard:
+                    observed=self.read()
+                    state={'setpoint_c':observed['temperature_c'],'temperature_c':observed['temperature_read_c'],
+                           'tec_current_a':observed['tec_current_a'],'current_a':observed['current_read_a'],'ld_enabled':observed['ld_enabled'],'tec_enabled':observed['tec_enabled']}
+                    if abs(observed['temperature_c']-previous_temperature)>.002:
+                        raise ValueError('External temperature setpoint change detected')
+                    # No client-supplied elapsed time; use the owner process clock.
+                    guard.check(state,candidate,time.monotonic()-previous_time,previous=previous_temperature)
+                for key in ('current_a','temperature_c'):
+                    if key in request:
+                        value = before[key] + (float(request[key]) - before[key]) * step / steps
+                        native = value if key == 'current_a' else (value - offset) / scale
+                        command = 'SOUR1:CURR' if key == 'current_a' else 'SOUR2:TEMP:SPO'
+                        self.command(f'{command} {native:.12g}')
+                        if key=='temperature_c':previous_temperature=value;previous_time=time.monotonic()
+            result = self.read()
+            for key in request:
+                tolerance = 6e-5 if key == "current_a" else .002
+                if abs(result[key] - float(request[key])) > tolerance:
+                    raise RuntimeError(f"CLD1015 setpoint verification failed: {key}")
+            return result
+
+    def enable(self, output, enabled):
+        with self.lock:
+            if output not in ("ld", "tec", "modulation") or not isinstance(enabled, bool):
+                raise ValueError("Select ld/tec/modulation and a boolean state")
+            state = self.read()
+            if enabled:
+                self.validate(dict(current_a=state["current_a"], temperature_c=state["temperature_c"]))
+            if output == "tec" and not enabled and state["ld_enabled"]:
+                raise ValueError("Turn LD off explicitly before turning TEC off")
+            command = {"ld": "OUTP1", "tec": "OUTP2", "modulation": "SOUR1:AM:STAT"}[output]
+            self.command(f"{command} {int(enabled)}")
+            result=self.read()
+            key={'ld':'ld_enabled','tec':'tec_enabled','modulation':'modulation_enabled'}[output]
+            if result[key] is not enabled:
+                raise RuntimeError('CLD1015 output enable verification failed: '+output)
+            return result
+
+    def validate_sweep(self, channels, waves, resolved):
+        state = self.read()
+        if not state["ld_enabled"] or not state["modulation_enabled"] or state["ld_mode"].upper() not in ("CURR", "CURRENT"):
+            raise ValueError("CLD1015 sweep requires LD on, constant-current mode and modulation enabled")
+        role = self.config["modulation_role"]
+        for c, actual in zip(channels, resolved):
+            if c["role"] != role:
+                continue
+            lo, hi = actual["offset_v"] - actual["amplitude_vpp"] / 2, actual["offset_v"] + actual["amplitude_vpp"] / 2
+            # DOC-104674 p56: 150 mA/V +/-5%. Check the total LD current,
+            # including the actual AWG baseline and controller DC setpoint.
+            extremes = [state["current_a"] + v * gain for v in (lo, hi) for gain in (.1425, .1575)]
+            for value in extremes:
+                check(value, self.config["current_limits_a"], "current")
+                if not 0 <= value <= state["current_limit_a"]:
+                    raise ValueError("AWG envelope exceeds CLD1015 current limit")
+            return
+        raise ValueError("Embedded CLD1015 modulation_role does not match a sweep channel")
+
+
+class MockIO:
+    def __init__(self, unit="C"):
+        self.unit, self.log, self.closed = unit, [], False
+        self.state = {"SOUR1:CURR": .05, "SOUR2:TEMP:SPO": 25., "OUTP1": 1, "OUTP2": 1,
+                      "SOUR1:AM:STAT": 1}
+
+    def query(self, command):
+        self.log.append(command)
+        if command == "*IDN?": return "THORLABS,CLD1015,DUMMY,1"
+        if command == "*OPC?": return "1"
+        if command == "SYST:ERR?": return '0,"No error"'
+        if command == "UNIT:TEMP?": return self.unit
+        fixed = {"SOUR1:CURR:LIM?": .1, "SOUR2:TEMP:LIM:LOW?": 10.,
+                 "SOUR2:TEMP:LIM:UPP?": 40., "SOUR1:FUNC:MODE?": "CURR", "SOUR2:FUNC:MODE?": "TEMP",
+                 "SENS3:CURR:DATA?": self.state["SOUR1:CURR"],
+                 "SENS2:TEMP:DATA?": self.state["SOUR2:TEMP:SPO"], "SOUR2:CURR:DATA?": .01}
+        return str(fixed[command] if command in fixed else self.state[command[:-1]])
+
+    def write(self, command):
+        self.log.append(command)
+        key, value = command.split()
+        self.state[key] = float(value)
+
+    def close(self):
+        self.closed = True

ldcon/drivers/cld1015_config.py

@@ -0,0 +1,31 @@
+"""Compile-time configuration; SI current and degrees Celsius at the public API."""
+import math
+
+
+def limits(value, name):
+    if value is None:
+        return None
+    result = tuple(float(v) for v in value)
+    if len(result) != 2 or not all(math.isfinite(v) for v in result) or result[0] >= result[1]:
+        raise ValueError(f"{name} must be an increasing finite pair")
+    return result
+
+
+def configuration(resource=None, *, current_limits_a=None, temperature_limits_c=None,
+                  timeout_s=5, mock=False, modulation_role=None,
+                  endpoint=None, instrument=None, temperature_conditions=None, temperature_writes_enabled=True, current_conditions=None, control_settings=None, current_writes_enabled=False, ld_enable_writes_enabled=False):
+    if type(ld_enable_writes_enabled) is not bool:
+        raise ValueError('ld_enable_writes_enabled must be a boolean')
+    return dict(resource=resource, current_limits_a=limits(current_limits_a, "current_limits_a"),
+                temperature_limits_c=limits(temperature_limits_c, "temperature_limits_c"),
+                timeout_s=float(timeout_s), mock=bool(mock), modulation_role=modulation_role,
+                endpoint=endpoint, instrument=instrument, temperature_conditions=temperature_conditions, temperature_writes_enabled=temperature_writes_enabled, current_conditions=current_conditions, control_settings=control_settings or {}, current_writes_enabled=current_writes_enabled, ld_enable_writes_enabled=ld_enable_writes_enabled)
+
+
+def check(value, bounds, name):
+    value = float(value)
+    if bounds is None:
+        raise ValueError(f"configure {name} safety limits before changing the setpoint")
+    if not math.isfinite(value) or not bounds[0] <= value <= bounds[1]:
+        raise ValueError(f"{name} {value} outside {bounds}")
+    return value

ldcon/drivers/dlcpro.py

@@ -0,0 +1,177 @@
+"""DLC Pro 1.9/3.2 USER console adapter; no connection is opened on import.
+
+Command reference pp. 38-43, 51-61, 118-119, 262. Exactly one console
+connection belongs to the instrument owner. Never retry a write after timeout.
+"""
+import json
+import math
+import re
+
+from ldcon.core.contracts import DeviceError
+
+
+from ldcon.drivers.dlcpro_console import Console, UncertainDLCWrite
+
+
+class DLCParameterError(DeviceError):
+    def __init__(self, path, code):
+        super().__init__(f'DLC parameter {path} returned error {code}')
+        self.path, self.code = path, code
+
+
+def _name(path):
+    if not isinstance(path, str) or not re.fullmatch(r'[a-z][a-z0-9:-]*', path):
+        raise ValueError('Invalid DLC parameter name')
+    return path
+
+
+def _atom(value):
+    if type(value) is bool:
+        return '#t' if value else '#f'
+    if type(value) not in (int, float) or not math.isfinite(value):
+        raise ValueError('DLC writes require finite numbers or booleans')
+    return repr(value)
+
+
+def parse_atom(text):
+    text = text.strip()
+    if text in ('#t', '#f'):
+        return text == '#t'
+    if text.startswith('"') and text.endswith('"'):
+        return json.loads(text)
+    try:
+        value = float(text)
+    except ValueError:
+        raise DeviceError('Unexpected DLC scalar reply') from None
+    if not math.isfinite(value):
+        raise DeviceError('Nonfinite DLC scalar reply')
+    return value
+
+
+class DLCPro:
+    """Unit-preserving parameter access. There is deliberately no eval/exec RPC."""
+    AXES = {'piezo': ('pc:voltage-set', 'pc:voltage-act', 'V'),
+            'temperature': ('tc:temp-set', 'tc:temp-act', 'degC'),
+            'current': ('cc:current-offset', 'cc:current-act', 'mA')}
+
+    def __init__(self, console):
+        self.console = console
+        self.unavailable_parameters = {}
+        self.compact_write_supported = False
+
+    @staticmethod
+    def path(channel, suffix):
+        if type(channel) is not int or channel not in (1, 2, 3, 4):
+            raise ValueError('Invalid DLC laser channel')
+        return _name(f'laser{channel}:dl:{suffix}')
+
+    def read(self, path):
+        path = _name(path)
+        reply = self.console.command(f"(param-ref '{path})")
+        error = re.fullmatch(r'Error: (-?\d+)(?: .*)?', reply)
+        if error:
+            raise DLCParameterError(path, int(error[1]))
+        return parse_atom(reply)
+
+    def read_optional(self, path):
+        """Only an explicit unknown/unavailable parameter means unsupported.
+
+        Transport failure, malformed data, and access denial still propagate.
+        The negative capability cache lives only for this connection.
+        """
+        if path in self.unavailable_parameters:
+            return None
+        try:
+            return self.read(path)
+        except DLCParameterError as error:
+            if error.code not in (-3, -20):
+                raise
+            self.unavailable_parameters[path] = error.code
+            return None
+
+    def identity(self, channel):
+        self.path(channel, 'serial-number')  # Validate before building names.
+        return dict(system_type=self.read('system-type'),
+                    serial_number=self.read('serial-number'),
+                    firmware_version=self.read('fw-ver'),
+                    product_name=self.read(f'laser{channel}:product-name'),
+                    head_serial_number=self.read(self.path(channel, 'serial-number')))
+
+    def verify_identity(self, serial_number, firmware_version=None):
+        identity = dict(serial_number=self.read('serial-number'),
+                        firmware_version=self.read('fw-ver'))
+        if identity['serial_number'] != serial_number:
+            raise DeviceError('DLC chassis identity mismatch')
+        if firmware_version is not None and identity['firmware_version'] != firmware_version:
+            raise DeviceError('DLC firmware differs from commissioned version')
+        return identity
+
+    def control_transaction(self):
+        return self.console.lock
+
+    def verify_compact_write_support(self):
+        # Constants only: this startup capability check reads/writes no outputs.
+        reply = self.console.command('(let ((status 0)) (list status 12.5))')
+        if self._pair(reply) != (0., 12.5):
+            raise DeviceError('DLC ordered result/readback expression unsupported')
+        self.compact_write_supported = True
+
+    @staticmethod
+    def _pair(reply):
+        match = re.fullmatch(r'\(\s*([^\s()]+)\s+([^\s()]+)\s*\)', reply.strip())
+        if not match:
+            raise DeviceError('DLC verification pair malformed')
+        return parse_atom(match[1]), parse_atom(match[2])
+
+    def write(self, path, value, *, tolerance=0., compact=False):
+        # The acknowledgement and readback form one indivisible transaction.
+        # Low-priority monitoring may not interleave between them.
+        with self.console.lock:
+            return self._verified_write(path, value, tolerance=tolerance, compact=compact)
+
+    def _verified_write(self, path, value, *, tolerance, compact):
+        path = _name(path)
+        # Any response other than exact success needs review. Code 2 is CLIPPED,
+        # not success; do not accept even if its subsequent readback happens to match.
+        if compact:
+            if not self.compact_write_supported:
+                raise DeviceError('Compact write capability was not verified')
+            # let forces param-set! to finish before param-ref. Merely putting
+            # both calls in list arguments would leave Scheme evaluation order unspecified.
+            expression = f"(let ((status (param-set! '{path} {_atom(value)}))) (list status (param-ref '{path})))"
+        else:
+            expression = f"(param-set! '{path} {_atom(value)})"
+        reply = self.console.command(expression, writing=True)
+        try:
+            status, actual = self._pair(reply) if compact else (parse_atom(reply), None)
+            if type(status) is bool or status != 0:
+                raise ValueError('DLC rejected, clipped or warned on write')
+            if not compact:
+                actual = self.read(path)
+            if type(value) is bool:
+                equal = actual is value
+            else:
+                equal = type(actual) is not bool and abs(actual - value) <= tolerance
+            if not equal:
+                raise ValueError('DLC setpoint readback mismatch')
+        except Exception as error:
+            raise UncertainDLCWrite('DLC write not verified; inspection required') from error
+        return actual
+
+    def snapshot(self, channel):
+        values = {}
+        for axis, (setting, measured, unit) in self.AXES.items():
+            values[axis] = dict(setpoint=self.read(self.path(channel, setting)),
+                                measured=self.read(self.path(channel, measured)), unit=unit)
+        values['current']['total_setpoint'] = self.read(self.path(channel, 'cc:current-set'))
+        values['piezo']['calculated_output'] = self.read_optional(self.path(channel, 'pc:voltage-out'))
+        values['piezo']['calculated_output_available'] = values['piezo']['calculated_output'] is not None
+        values['feedforward_master'] = self.read_optional(f'laser{channel}:feedforward-master')
+        values['unavailable_parameters'] = dict(self.unavailable_parameters)
+        values['emission'] = self.read(self.path(channel, 'cc:emission'))
+        values['pzt_enabled'] = self.read(self.path(channel, 'pc:enabled'))
+        values['tec_enabled'] = self.read(self.path(channel, 'tc:enabled'))
+        values['tec_fault'] = self.read(self.path(channel, 'tc:fault'))
+        values['ff_enabled'] = self.read(self.path(channel, 'cc:feedforward-enabled'))
+        values['ff_factor_ma_per_v'] = self.read(self.path(channel, 'cc:feedforward-factor'))
+        return values

ldcon/drivers/dlcpro_analog.py

@@ -0,0 +1,33 @@
+"""Documented Fine inputs and ARC readback, using the owner's console.
+
+Fine readbacks have no device acquisition timestamp. The host request interval
+is retained and must not be presented as a synchronous ADC/WSU acquisition.
+"""
+import time
+
+
+INPUTS = {'fine1': ('io:fine-1:value-act', 0),
+          'fine2': ('io:fine-2:value-act', 1)}
+
+
+def inspect(driver, channel, *, clock=time.monotonic, utc=time.time):
+    result = {'inputs': {}, 'routes': {}}
+    for name, (path, _) in INPUTS.items():
+        start, wall = clock(), utc()
+        value = driver.read(path)
+        result['inputs'][name] = dict(value_v=value, started_s=start,
+            completed_s=clock(), started_unix_s=wall, completed_unix_s=utc(),
+            acquisition_timestamp_available=False)
+    for axis in ('pc', 'cc', 'tc'):
+        result['routes'][axis] = {key: driver.read(driver.path(channel,
+            f'{axis}:external-input:{key}')) for key in ('enabled', 'signal', 'factor')}
+    return result
+
+
+def read_input(driver, name, *, clock=time.monotonic, utc=time.time):
+    path, _ = INPUTS[name]
+    start, wall = clock(), utc()
+    value = driver.read(path)
+    return dict(value_v=value, started_s=start, completed_s=clock(),
+                started_unix_s=wall, completed_unix_s=utc(),
+                acquisition_timestamp_available=False)

ldcon/drivers/dlcpro_console.py

@@ -0,0 +1,133 @@
+"""Bounded DLC Telnet framing, without telnetlib or terminal emulation."""
+import socket
+import time
+from ldcon.drivers.dlcpro_priority import PriorityLock
+
+from ldcon.core.contracts import DeviceError
+
+
+class UncertainDLCWrite(DeviceError):
+    """A write may have reached the controller; never replay automatically."""
+
+
+class Console:
+    def __init__(self, stream, *, max_reply_bytes=262144, timeout_s=2.):
+        self.stream = stream
+        self.max_reply_bytes = max_reply_bytes
+        self.timeout_s = timeout_s
+        self.lock = PriorityLock()
+        self.broken = False
+        self._telnet_state = 'data'
+        self._verb = None
+        self.greeting = self._reply()
+
+    @classmethod
+    def connect(cls, host, *, port=1998, timeout_s=2.):
+        stream = socket.create_connection((host, port), timeout=timeout_s)
+        stream.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+        try:
+            console = cls(stream, timeout_s=timeout_s)
+            # FW 1.9 echoes each character despite rejecting Telnet ECHO.
+            # This console-local setting avoids per-character reply overhead;
+            # it changes no laser parameter and leaves other consoles alone.
+            if console.command("(param-set! 'echo #f)") != '0':
+                raise DeviceError('DLC console echo disable rejected')
+            if console.command("(param-ref 'echo)") != '#f':
+                raise DeviceError('DLC console echo disable not verified')
+            return console
+        except BaseException:
+            stream.close()
+            raise
+
+    def _decode_telnet(self, raw):
+        text = bytearray()
+        for byte in raw:
+            state = self._telnet_state
+            if state == 'data':
+                if byte == 255:
+                    self._telnet_state = 'iac'
+                else:
+                    text.append(byte)
+            elif state == 'iac':
+                if byte == 255:
+                    text.append(byte)
+                    self._telnet_state = 'data'
+                elif byte in (251, 252, 253, 254):
+                    self._verb = byte
+                    self._telnet_state = 'option'
+                elif byte == 250:
+                    self._telnet_state = 'subnegotiation'
+                else:
+                    self._telnet_state = 'data'
+            elif state == 'option':
+                # We need no terminal options. Reject WILL with DONT and DO with
+                # WONT; acknowledgments are ignored to avoid negotiation loops.
+                if self._verb in (251, 253):
+                    self.stream.sendall(bytes((255, 254 if self._verb == 251 else 252, byte)))
+                self._telnet_state = 'data'
+            elif state == 'subnegotiation':
+                if byte == 255:
+                    self._telnet_state = 'subnegotiation_iac'
+            elif state == 'subnegotiation_iac':
+                self._telnet_state = 'data' if byte == 240 else 'subnegotiation'
+        return text
+
+    def _reply(self):
+        result = bytearray()
+        received = 0
+        deadline = time.monotonic() + self.timeout_s
+        while not ((result == b'> ' or result.endswith(b'\n> '))
+                   and self._telnet_state == 'data'):
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError('DLC reply deadline exceeded')
+            if hasattr(self.stream, 'settimeout'):
+                self.stream.settimeout(remaining)
+            block = self.stream.recv(4096)
+            if not block:
+                raise ConnectionError('DLC console disconnected before prompt')
+            self._quick_ack()
+            received += len(block)
+            if received > self.max_reply_bytes:
+                raise DeviceError('DLC reply exceeds framing bound')
+            result.extend(self._decode_telnet(block))
+        return result[:-2].replace(b'\r\x00', b'\r').decode('utf-8').strip()
+
+    def _quick_ack(self):
+        # Linux QUICKACK is transient: request it for each received fragment.
+        # This can unblock a peer's small remaining reply/prompt under Nagle;
+        # our TCP_NODELAY only controls requests sent from this socket. It is
+        # an optional transport optimization, never a change to reply bounds.
+        option = getattr(socket, 'TCP_QUICKACK', None)
+        configure = getattr(self.stream, 'setsockopt', None)
+        if option is not None and configure is not None:
+            try:
+                configure(socket.IPPROTO_TCP, option, 1)
+            except OSError:
+                pass  # Unsupported socket/platform keeps the original framing.
+
+    def command(self, expression, *, writing=False):
+        if not isinstance(expression, str) or any(c in expression for c in '\r\n\x00'):
+            raise ValueError('DLC command must be one line')
+        with self.lock:
+            if self.broken:
+                raise DeviceError('DLC console requires inspection/reconnection')
+            try:
+                if hasattr(self.stream, 'settimeout'):
+                    self.stream.settimeout(self.timeout_s)
+                self.stream.sendall((expression + '\n').encode('ascii'))
+                reply = self._reply()
+                lines = reply.splitlines()
+                # Firmware 1.9 may echo even after ECHO negotiation is rejected.
+                # Remove only the exact request on its own first line.
+                if lines and lines[0] == expression:
+                    reply = '\n'.join(lines[1:]).strip()
+                return reply
+            except Exception as error:
+                self.broken = True
+                if writing:
+                    raise UncertainDLCWrite('DLC write outcome unknown; no replay') from error
+                raise DeviceError('DLC read failed') from error
+
+    def close(self):
+        self.stream.close()