plesty.pm100d.sensors
=====================

.. py:module:: plesty.pm100d.sensors

.. autoapi-nested-parse::

   What the sensor head fitted to a PM100D can and cannot be asked.

   The meter's SCPI vocabulary is fixed; what it can *answer* is not. A silicon
   photodiode has no pyroelectric element and no temperature probe, so
   ``MEAS:ENER?`` and ``MEAS:TEMP?`` are simply never answered. That silence is
   worse than an error: the transport reads it as a wedged instrument and
   escalates through a device clear and a session reopen, and repeating it wedges
   the meter for real.

   So the gaps are recorded per sensor in ``sensor_capabilities.json`` and looked
   up at runtime, rather than hardcoded into whatever happens to be attached
   today.



Attributes
----------

.. autoapisummary::

   plesty.pm100d.sensors._CAPABILITIES_FILE
   plesty.pm100d.sensors.DEFAULT_KEY


Functions
---------

.. autoapisummary::

   plesty.pm100d.sensors.load_capabilities
   plesty.pm100d.sensors.unsupported_ops
   plesty.pm100d.sensors.param_limits
   plesty.pm100d.sensors.known_sensors
   plesty.pm100d.sensors.read_sensor_name


Module Contents
---------------

.. py:data:: _CAPABILITIES_FILE

.. py:data:: DEFAULT_KEY
   :value: '_default'


.. py:function:: load_capabilities() -> dict[str, Any]

   Return the sensor capability map, keyed by sensor name.

   :returns: The parsed document. Keys beginning with ``_`` are metadata, except
             :data:`DEFAULT_KEY` which is the fallback entry.


.. py:function:: unsupported_ops(sensor: str | None) -> list[str]

   Return the operations *sensor* cannot perform.

   :param sensor: Sensor name as reported by ``SYST:SENS:IDN?``, or ``None`` when
                  it could not be read.

   :returns: Operation names to keep away from this sensor. An unknown sensor gets
             the conservative default — the union of every known head's gaps —
             because driving an unanswerable query is what wedges the meter.


.. py:function:: param_limits(sensor: str | None) -> dict[str, tuple[float, float]]

   Return the parameter ranges *sensor* actually accepts.

   The schema carries the console-wide envelope on purpose — the same module
   serves every head — so the fitted sensor's narrower limits belong here and
   are applied at connect.

   :param sensor: Sensor name as reported by ``SYST:SENS:IDN?``.

   :returns: ``{parameter: (min, max)}``, empty when nothing is recorded for this
             head. An unrecorded sensor keeps the console envelope rather than
             inheriting another head's limits.


.. py:function:: known_sensors() -> list[str]

   Return the sensor names with a recorded entry.


.. py:function:: read_sensor_name(device: Any) -> str | None

   Read the fitted sensor's name from a connected device.

   :param device: A connected PM100D device.

   :returns: The sensor name (the first field of ``SYST:SENS:IDN?``), or ``None``
             when it cannot be read — in which case callers should fall back to the
             conservative default rather than assume the sensor is capable.