:orphan:

.. _device-MDT694B:

MDT694B
=======

**From:** `Thorlabs <https://www.thorlabs.com/newgrouppage9.cfm?objectgroup_id=1191>`_
**Class:** :py:class:`herosdevices.hardware.thorlabs.mdt69xb.MDT694B`

**Driver Quality Index:** beta

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

.. dropdown:: Thorlabs MDT69xx USB Configuration


    **Problem**

    The USB chip in the Thorlabs MDT69xx series (e.g., MDT693B) may identify as a **Human Interface Device (HID)**.
    If the ``usbhid`` kernel driver binds to it, the device cannot be accessed via a serial interface, rendering it non-functional.

    **Solution: udev Rule**

    1. **Identify Vendor and Product IDs**

       Run the following command to list all USB devices and locate the Thorlabs device::

          lsusb

       Example output::

          Bus 001 Device 003: ID xxxx:xxxx Thorlabs MDT693B

       Note the ``xxxx`` values for ``idVendor`` and ``idProduct``.

    2. **Find the USB Kernel Path**

       Use ``udevadm`` to inspect the device attributes and locate the **kernel path** (e.g., ``1-8:1.0``)::

          udevadm info -a -p $(udevadm info -q path -n /dev/bus/usb/XXX/YYY)

       Replace ``XXX`` and ``YYY`` with the bus and device numbers from ``lsusb``.
       This command will print a lot of information. You are looking for a line like::

          looking at device '/devices/pci0000:00/0000:00:14.0/usb1/1-8/1-8:1.0/0003:046A:B090.0002/hidraw/hidraw1':

       Here, the ``1-8:1.0`` is what you are looking for.

    3. **Create the udev Rule**

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

          # Thorlabs piezo controller MDT693B
          ACTION=="add", DRIVERS=="usb", ATTRS{idVendor}=="xxxx", ATTRS{idProduct}=="xxxx", SYMLINK+="USB_PIEZO_CTRL_1", RUN+="echo -n 'kernel_path' > /sys/bus/usb/drivers/usbhid/unbind"

       Replace:

       - ``xxxx`` with the **Vendor and Product IDs** from Step 1.
       - ``kernel_path`` with the **USB kernel path** from Step 2 (e.g., ``1-5.1.2.3:1.0``).

    4. **Reload udev Rules**

       Apply the changes by reloading the udev rules::

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


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

Device driver for the MDT694B Single Channel, Open-Loop Piezo Controller.

.. 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.mdt69xb.MDT694B` 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
           * - **address**
             - **<class 'str'>**
             - 
             - Serial address of the device. 
           * - timeout
             - <class 'float'>
             - 1.0
             - timeout for read operations.

    .. tab-item:: Example JSON for BOSS

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

        .. code-block:: json

            {
                "_id": "my-piezo-controller",
                "classname": "herosdevices.hardware.thorlabs.MDT694B",
                "active": false,
                "arguments": {
                    "address": "/dev/ttyUSB0"
                }
            }

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

        .. code-block:: json

            {
                "_id": "my_MDT694B",
                "classname": "herosdevices.hardware.thorlabs.mdt69xb.MDT694B",
                "arguments": {
                    "address": "/dev/ttyUSB0",
                    "timeout": 1.0
                }
            }

        :sup:`generated from signature`

    .. tab-item:: Inheritance

        .. inheritance-diagram:: herosdevices.hardware.thorlabs.mdt69xb.MDT694B