:orphan:

.. _device-PM100:

PM100
=====

**From:** `Thorlabs <https://www.thorlabs.com/thorproduct.cfm?partnumber=PM100D>`_
**Class:** :py:class:`herosdevices.hardware.thorlabs.pm100.PM100`

**Driver Quality Index:** beta

Additional Information :bdg-warning:`Check before use`
------------------------------------------------------

.. dropdown:: Thorlabs PM100 USB Configuration


    The Thorlabs PM100 series optical power and energy meters (e.g. PM100D) are USBTMC devices. Out of the box, two
    steps are required before they can be used with the :py:class:`herosdevices.hardware.thorlabs.pm100.PM100`
    driver.

    **Setting the driver mode**

    The device must be switched to the NI-VISA (WinUSB) driver mode. By default the devices are configured for
    the Thorlabs Windows driver, in which case the Linux ``usbtmc`` kernel driver does not bind to the device
    and no ``/dev/usbtmc*`` device node appears.

    The driver mode is switched with the Thorlabs Optical Parameter Monitor GUI:

    1. Download and install the Power Console software from the
       `Thorlabs software page <https://www.thorlabs.com/software-pages/OPM>`_ (Windows required).
    2. Connect the power meter and start the Power Console.
    3. Navigate to ``Help -> Tools -> Driver Switcher``.
    4. Switch the driver mode to NI-VISA.

    The setting is stored in the device, so this step only has to be performed once per device. After reconnecting
    the device on Linux, a ``/dev/usbtmc*`` device node should appear.

    **Udev Rules (Linux)**

    The ``/dev/usbtmc*`` device nodes and the raw usb device are only accessible by root, so a udev rule is required to grant access
    to regular users.

    1. Edit or create a new udev rules file (e.g. ``/etc/udev/rules.d/99-thorlabs-pm100.rules``) and add the
       following rule::

          # Thorlabs PM100 series power meters
          SUBSYSTEM=="usb", ATTRS{idVendor}=="1313", MODE="0660", GROUP="plugdev"
          KERNEL=="usbtmc[0-9]", ATTRS{idVendor}=="1313", MODE="0660", GROUP="plugdev"


       Make sure your user is in the ``plugdev`` group or replace ``plugdev`` with a group your user is a member of

    2. Apply the changes by reloading the udev rules::

          sudo udevadm control --reload-rules
          sudo udevadm trigger --action=add

    .. warning::

        Note, that if a device file (``/dev/usbtmc0``) is used as ``resource`` argument, the device can not be restarted and needs to be
        reconnected to the host due to the PyVISA backend removing the ``/dev/usbtmc0`` link upon access. You need to
        use a VISA string (printed on startup of the device) to be able to restart it for example via BOSS.


....................

Device driver for the Thorlabs PM100A/D optical power and energy meter.

The device is controlled via SCPI commands over a VISA connection (typically USBTMC).

.. tab-set:: 

    .. tab-item:: Arguments

        Bold arguments are mandatory. For more information on the listed arguments refer to the class             documentation: :py:class:`herosdevices.hardware.thorlabs.pm100.PM100` If parameters appear in this             list but not in the class definition, please recursively check the linked base classes for the             definition of the parameter.

        .. list-table:: 
           :widths: 50 50 50 100
           :header-rows: 1

           * - Argument
             - Type
             - Default Value
             - Description
           * - **resource**
             - **<class 'str'>**
             - 
             - 
           * - keep_alive
             - <class 'bool'>
             - True
             - Keep the VISA connection open between operations.

    .. tab-item:: Example JSON for BOSS

        The following JSON strings can be used to start a HERO device representation of             :py:class:`PM100 <herosdevices.hardware.thorlabs.pm100.PM100>` using             `BOSS <https://boss-eb4966.gitlab.io/>`_.

        .. code-block:: json

            {
                "_id": "my_powemeter",
                "classname": "herosdevices.hardware.thorlabs.PM100",
                "arguments": {
                    "resource": "USB::0x1313::0x8078::P0019289::INSTR"
                }
            }

        :sup:`from examples/thorlabs/pm100d.json`

        .. code-block:: json

            {
                "_id": "my_PM100",
                "classname": "herosdevices.hardware.thorlabs.pm100.PM100",
                "arguments": {
                    "resource": "<class 'str'>",
                    "keep_alive": true
                }
            }

        :sup:`generated from signature`

    .. tab-item:: Inheritance

        .. inheritance-diagram:: herosdevices.hardware.thorlabs.pm100.PM100