:orphan:

.. _device-Menlo OFC:

Menlo OFC
=========

**From:** `Menlo Systems <https://www.menlosystems.com/>`_
**Class:** :py:class:`herosdevices.hardware.menlo.ofc.OFC`

**Driver Quality Index:** alpha

.. admonition:: Requires the following packages 

    `pywebchannel <https://github.com/MenloSystems/pywebchannel>`_

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

.. dropdown:: Menlo OFC Setup


    This driver is split into one core device and several modules attached to it.

    :py:class:`~herosdevices.hardware.menlo.OFC` opens the single QWebChannel websocket connection to the comb and
    exposes its raw control/status tree via ``get_node``/``set_node``/``explore``.

    Each functional-layer module (:py:class:`~herosdevices.hardware.menlo.DDS`,
    :py:class:`~herosdevices.hardware.menlo.LaserLock`, :py:class:`~herosdevices.hardware.menlo.DualLaserLock`,
    :py:class:`~herosdevices.hardware.menlo.FXE`, :py:class:`~herosdevices.hardware.menlo.RepetitionRate`,
    :py:class:`~herosdevices.hardware.menlo.CEO`, :py:class:`~herosdevices.hardware.menlo.Oscillator`) is a
    separate HERO. It takes the already-running ``OFC``
    HERO as a constructor argument via BOSS's ``"ofc": "$device_menlo_ofc"`` reference, so all modules share the
    one physical connection instead of each opening their own.

    See ``examples/menlo/ofc.json`` for a complete BOSS config wiring one comb with all its modules.

    Some CW channels lock two wavelengths through one shared lock loop, with two separate frequency-distribution
    blocks instead of one. Deploying plain ``LaserLock`` against one of these fails, since it hardcodes a single
    frequency-distribution node name that these channels don't have. Use
    :py:class:`~herosdevices.hardware.menlo.DualLaserLock` instead, passing both wavelengths' node names
    explicitly; see ``examples/menlo/ofc.json`` for an example.

    :py:class:`~herosdevices.hardware.menlo.FXE` wraps the comb's 16-channel frequency counter. Unlike the other
    modules, it has no default observables, since which channel carries which signal is deployment-specific.
    Pass ``observables`` for the channels relevant to your comb, e.g. a beat on channel 3:

    .. code-block:: json

       "arguments": {
         "ofc": "$device_ofc",
         "observables": {
           "cw_beat": {"path": "counterFrequencies.channel03", "unit": "Hz"}
         }
       }

    Node paths (used in ``get_node``/``set_node``/``observables``) are firmware-dependent and not documented by
    Menlo. Use :py:meth:`~herosdevices.hardware.menlo.OFC.format_tree` to find them interactively:

    .. code-block:: pycon

       >>> print(ofc.format_tree("functionalLayer.rrSettings", depth=2))
       functionalLayer.rrSettings
       |-- dds
       |   |-- ddsFrequency = 28286800
       |   |-- outputOn = True
       |   `-- outputPower = 0.64
       |-- mainControls
       |   |-- fastOutput ...
       |   |-- lock = True
       |   `-- slowOutput ...
       `-- repetitionRate
           |-- rrCounterRepRate = 250105340.0
           `-- rrTargetBeatRF = 250105340

    Nodes shown as ``...`` are unexpanded branches; raise ``depth`` or call ``format_tree`` again rooted at that
    path to descend further. :py:meth:`~herosdevices.hardware.menlo.OFC.explore` returns the same tree as a plain
    dict instead of a rendered string, if you want to process it programmatically.

    For anything specific to your comb (e.g. a customer-specific fiber-noise-cancellation module),
    poll or control it directly instead of adding a new class: every module accepts an ``observables`` argument,
    merged on top of its ``DEFAULT_OBSERVABLES``, and ``OFC.get_node``/``OFC.set_node`` give full read/write
    access to any node regardless.

    .. code-block:: json

       "arguments": {
         "host": "IP_OR_HOSTNAME",
         "observables": {
           "fnc578_locked": {"path": "functionalLayer.fnc578Settings.mainControls.lock", "unit": ""},
           "fnc1157_locked": {"path": "functionalLayer.fnc1157Settings.mainControls.lock", "unit": ""}
         }
       }

    .. important::

       The ``OFC`` device's ``_ensure_connected`` method must be reachable from the other modules over the
       network. HEROS excludes underscore-prefixed methods from a ``RemoteHERO`` proxy unless marked
       ``force_remote``, so the ``OFC`` row in your BOSS config needs:

       .. code-block:: json

          "extra_decorators": [["_ensure_connected", "heros.inspect.force_remote"]]

       See ``examples/menlo/ofc.json`` for this in context.

    .. warning::

       The PyPI package named ``pywebchannel`` is an unrelated project; installing it will not work. Install it
       from source instead:

       .. code-block:: bash

          pip install "pywebchannel @ git+https://github.com/MenloSystems/pywebchannel"

       ``pywebchannel`` is not declared as a project dependency, so this install step must be run manually wherever the Menlo driver
       is used: locally, in CI, and in any Docker image.

       In a Docker Container deployment via BOSS, use the ``BOSS_PIP_PKGS`` environment variable (see the
       `BOSS documentation <https://boss-eb4966.gitlab.io/getting_started.html#additional-dependencies-in-docker>`_)
       instead of extending the image:

       .. code-block:: yaml
          :caption: docker-compose.yml

           services:
             device_ofc:
               image: registry.gitlab.com/atomiq-project/herosdevices:latest
               restart: always
               network_mode: host
               volumes:
                 - ./ofc.json:/ofc.json:ro
               environment:
                 - BOSS_PIP_PKGS=pywebchannel@git+https://github.com/MenloSystems/pywebchannel
               command: python -m boss.starter -u file:///ofc.json --log info


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

Driver for a Menlo Systems optical frequency comb (OFC) exposed via the QWebChannel websocket interface.

The OFC exposes its full control/status tree (functional layer, modules, settings, ...) via Qt's
WebChannel protocol. Because that tree is deep and firmware-dependent, individual nodes are addressed by
dotted path strings (see :py:meth:`get_node`) instead of being declared as fixed class attributes. Use
:py:meth:`explore` interactively to discover which paths are available on a given device, then list the
ones you want polled in `observables`.

Values are pushed by the device and kept in a local cache as soon as the connection is established, so
:py:meth:`get_node` and :py:meth:`_observable_data` never trigger network traffic themselves.

.. 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.menlo.ofc.OFC` 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
           * - **host**
             - **<class 'str'>**
             - 
             - Hostname or IP address of the OFC's QWebChannel websocket endpoint.
           * - port
             - <class 'int'>
             - 8002
             - Port of the websocket endpoint.
           * - user
             - <class 'str'>
             - guest
             - Username used for authentication.
           * - password
             - <class 'str'>
             - 
             - Password used for authentication.
           * - timeout
             - <class 'float'>
             - 5.0
             - Seconds to wait for a single connection attempt, see :py:class:`QWebChannelConnection`.
           * - reconnect_cooldown
             - <class 'float'>
             - 30.0
             - Minimum seconds between two connection attempts, see :py:class:`QWebChannelConnection`. Keeps a prolonged outage (e.g. the OFC being powered off for half an hour) from causing a reconnect attempt on every single poll tick; the OFC is picked back up automatically the next time it is read after coming back online, no restart needed.
           * - observables
             - dict[str, dict[str, str]] | None
             - None
             - Additional observables to poll, merged on top of :py:attr:`DEFAULT_OBSERVABLES` (an entry here with the same name overrides the default) rather than replacing it. Each entry maps the name under which a value is emitted with the `observable_data` event to a dict with keys "path" (dotted node path, see :py:meth:`get_node`) and "unit". The repetition-rate, CEO, and oscillator modules have their own default observables instead, see :py:class:`~herosdevices.hardware.menlo.RepetitionRate`, :py:class:`~herosdevices.hardware.menlo.CEO`, and :py:class:`~herosdevices.hardware.menlo.Oscillator`.

    .. tab-item:: Example JSON for BOSS

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

        .. code-block:: json

            {
                "_id": "device_menlo_ofc",
                "classname": "herosdevices.hardware.menlo.OFC",
                "arguments": {
                    "host": "IP_OR_HOSTNAME"
                },
                "extra_decorators": [
                    [
                        "_ensure_connected",
                        "heros.inspect.force_remote"
                    ]
                ],
                "datasource": {
                    "async": false,
                    "interval": 15
                }
            }

        :sup:`from examples/menlo/ofc.json`

        .. code-block:: json

            {
                "_id": "my_OFC",
                "classname": "herosdevices.hardware.menlo.ofc.OFC",
                "arguments": {
                    "host": "<class 'str'>",
                    "port": 8002,
                    "user": "guest",
                    "password": "",
                    "timeout": 5.0,
                    "reconnect_cooldown": 30.0,
                    "observables": null
                }
            }

        :sup:`generated from signature`

    .. tab-item:: Inheritance

        .. inheritance-diagram:: herosdevices.hardware.menlo.ofc.OFC