.. _thorlabs_pm100_configuration:

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.
