*******************
Software operation
*******************

The following steps will guide you through the features of the WebSQ driver software running on your Single Quantum system.

The software was developed to make your work as convenient and efficient as possible. We achieve this by omitting any software installation on your computer as it is controlled through the Web Browser of your choice!

This innovative concept makes the control of the superconducting single photon detectors

* operating system independent,
* device independent,
* location independent,
* stable,
* multi-user access friendly, and,
* long term operational, as only backwards compatible web standards are used.

All these features together allow for a complete new way of using scientific equipment:

* No time is wasted of installing and setting up proprietary software and drivers which only run on a limited set of operating systems.
* The operator can use a mobile device such as a tablet or a mobile phone right at the work place for a faster and more convenient alignment procedure.
* The software is running where you are - it runs at same time on multiple browsers on multiple platforms.
* You can change it! The software is Open Source and allows you to change it to your wishes allowing integration into the most demanding applications.

Connection
=============

The WebSQ driver is connected over an Ethernet connection either directly with a computer or through a router.

Its default configuration is:

* IP Address: 	192.168.1.1 or sq.local
* Runs a DHCP server providing the address range 192.168.1.5 till 192.168.1.200
* Username: 	user
* Password: 	websq

If you connect directly to your computer just enter the IP address (192.168.1.1) in your browser and you can start working.
Or even more conveniently, it is also possible to access the WebSQ driver through its default name::

    sq.local/

with your browser. In general, you can reach the system at 'hostname.local/', the hostname can be changed in the 'Networking' tab in 'Config' (wrench symbol on top of the page).

If you are connecting to a router with Wifi access you can directly access the driver with any computer or mobile device. Please make sure that in this case you have to disable the DHCP server ('Networking' tab).
For more details about networking configuration, see :ref:`network-setup`.

.. _websq_inteface:

The WebSQ Interface
=========================
Login
-------------------------
.. _fig_Software_Login:
.. figure:: ./graphics/manual_screenshots/Login.png
    :scale: 80 %

    Login Screen.


Once you have successfully connected a browser with your WebSQ driver you will see the above login prompt.
For the first login you should use the standard credentials:
    * Username: 	user
    * Password: 	websq

You can change the username/password in the 'Access Control' tab in 'Config' (wrench symbol on top of the page).

The icons on the top of the page allow you to navigate between different windows:

.. raw:: html

    <ul>
      <li><i class="fa fa-home"></i> Home window where the detected photons are displayed and the most important settings can be accessed.</li>
      <li><i class="fa fa-sliders"></i> Tune window to find optimal working conditions of the SNSPDs.</li>
      <li><i class="fa fa-asterisk"></i> Temperature window showing the temperature history of the cryostat.</li>
        <li><i class="fa fa-wrench"></i> Configuration window.</li>
        <li><i class="fa fa-question"></i> Help window where you find the manual and example code.</li>
        <li><i class="fa fa-sign-in"></i>/<i class="fa fa-sign-out"></i> Login/Logout button.</li>
        <li><i class="fa fa-power-off"></i> Shutdown button.</li>
    </ul>

.. raw:: latex

    \begin{itemize}
        \item \faHome\,Home window where the detected photons are displayed and the most important settings can be accessed.
        \item \faSliders\,Tune window to find optimal working conditions of the SNSPDs.
        \item \faAsterisk\,Temperature window showing the temperature history of the cryostat.
        \item \faWrench\,Configuration window.
        \item \faQuestion\,Help window where you find the manual and example code.
        \item \faSignIn\,/\,\faSignOut\,Login/Logout button.
        \item  \faPowerOff\,Shutdown button.
    \end{itemize}


Home Window
---------------------------
.. _fig_Software_Bias:
.. figure:: ./graphics/manual_screenshots/Bias_Home.png

    Home Window

The home window displays the most important features used to control and monitor the function of the superconducting nanowire single photon detectors (SNSPD).
It is divided into three groups:

* Real Time Monitor
* Control
* Alignment Helper

.. _real-time-monitor:

Real Time Monitor.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Real Time Monitor window displays a time trace of the detected photons for each detector.
A right click on the plot window opens a a dialog to choose 'Automatic' or 'Manual' Y-axis scaling.

There are four input groups underneath the plot window:\

.. raw:: html

    <ul>
      <li>The <i class="fa fa-play"></i> symbol is used to switch on the detection system by enabling the SNSPDs' bias currents.</li>
      <li>The input field sets the photon counting integration time.</li>
      <li>The Recording group (<i class="fa fa-dot-circle-o"></i>&nbsp<i class="fa fa-stop"></i>&nbsp<i class="fa fa-pencil"></i>&nbsp<i class="fa fa-download"></i>) allows you to record the measured counts and download them to your computer:
        <ul>
            <li><i class="fa fa-dot-circle-o"></i> Starts the recording (Limit: 1'000'000 lines based on first in last out),</li>
            <li><i class="fa fa-stop"></i> Stops recording and deletes the stored file,</li>
            <li><i class="fa fa-pencil"></i> Allows to name the file and add comments,</li>
            <li><i class="fa fa-download"></i> Downloads the recorded file.</li>
        </ul>
        <li>the <i class="fa fa-refresh"></i> button clears the plot window from old data points. That's especially helpful to speed up automatic rescaling of the y-axis.</li>
    </ul>

.. raw:: latex

    \begin{itemize}
        \item The	\faPlay\,symbol is used to switch on the detection system by enabling the SNSPDs' bias currents.
        \item The input field sets the photon counting integration time.
        \item The Recording group (\faDotCircleO\, \faStop\,\faPencil\,\faDownload) allows you to record the measured counts and download them to your computer:
        \begin{itemize}
            \item \faDotCircleO\, Starts the recording (Limit: 1'000'000 lines based on first in last out),
            \item \faStop\, Stops recording and deletes the stored file,
            \item \faPencil\, Allows to name the file and add comments,
            \item \faDownload\, Downloads the recorded file.
        \end{itemize}
        \item the \faRefresh\, button clears the plot window from old data points. That's especially helpful to speed up automatic rescaling of the y-axis.
    \end{itemize}


.. rubric:: Tips for Keyboard shortcuts: Three preset values of the integration time (10, 100, 1000 ms) are mapped onto the 	keys 'q', 'w', and 'e'. The 'delete key' clears the plot window.

Control
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This window shows the counted photons, allows to control the SNSPDs' bias currents, and the corresponding trigger levels.
The column names **Visible**, **Bias Current (μA)**, **Trigger Level (mV)**, as well as the **Photon Counts** are all clickable.

Click on:

* **Counts**: Shows the photon counts large on the screen - ideal for alignment.
* **Visible**: Toggles the visibility of the plot lines.
* **Bias Current (μA)**: Opens a dialog to select the increments.
* **Trigger Level (mV)**: Opens a dialog to select the increments.


.. rubric:: Tip: Click on a photon counts field and the value will be displayed large on the screen - ideal for alignment.

Alignment Helper
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. raw:: html

    <p>Clicking on the <i class="fa fa-volume-off"></i> symbol activates a tone. Its frequency is proportional to the photon counts of the selected channel.<br>
    To give the most accurate feedback there is a photon count rollover (standard: 1 MCnts). When more photons than the rollover value are measured the audio frequency rolls over and starts from the lowest tone again.
    The rollover value and the tone type (square, sine, sawtooth, triangle) can be changed in <i class="fa fa-wrench"></i> under the <em>Sound</em> tab.</p>

.. raw:: latex

    Clicking on the \faVolumeOff\, symbol activates a tone. Its frequency is proportional to the photon counts of the selected channel.

    To give the most accurate feedback there is a photon count rollover implemented (standard value: 1 MCnts). When more photons than the rollover value are measured the audio frequency rolls over and starts from the lowest tone again.
    The rollover value and the tone type (square, sine, sawtooth, triangle) can be changed in \faWrench\, under the \emph{Sound} tab.

.. _fig_alignment-helper:
.. figure::  ./graphics/manual_screenshots/Set_Sound-led.png

   Setting for the sound rollover and for the LED in the on/off button.


Detector operation
---------------------------

.. _fig_ivTooltip:
.. figure:: ./graphics/ivTooltip.png

    Detector Tuning tab showing measured current-voltage and current-counts graph. Tooltips provide the precise measured data at the mouse pointer's position.

A SNSPD needs a properly set bias current to operate at peak performance - highest detector efficiency is achieved when the SNSPD is biased closely to the critical-current.
The critical current represents the transition between the superconductive and the resistive state of the detector. Once the detector is biased with a current higher than the critical current, a sharp rise of the detector voltage is observed.
For example, the critical current of detector 2 is 11.40 μA as shown on the tooltip in :numref:`fig_ivTooltip`.
The detector tuning tab helps finding the proper bias current.
The easiest way is the Auto Search tool, see :numref:`fig_auto_search`. This can be evoked by clicking on the magnifying glass. In the Auto Search dialog you specify the required dark count rate per detector.
It is important to make sure that no light is reaching the detector during this search. If the Auto Search can not find the right bias-current it will be indicated with a "-" sign.

.. _fig_auto_search:
.. figure:: ./graphics/auto_search_notf.png

    Detector current auto search dialog. If a bias current can not be found it is indicated with a "-" sign.

Detector Temperature
--------------------------
.. _fig_detector_temperature:
.. figure:: ./graphics/manual_screenshots/Temp.png

    Detector temperature trace.

The detector temperature trace is especially useful to check the temperature of the detectors during cool-down and warm-up. By clicking on the download icon in the upper right corner
of the temperature plot window the temperature history can be downloaded, see :numref:`fig_detector_temperature`. Note, the temperature history spans the time since the last startup, i.e. switching off the driver will delete all temperature data.
The maximum file length is limited to one million temperature entries. If this length is reached incoming temperature data will be kept on a first in last out basis.


Configuration
---------------------------
Here you can configure the following settings:

* Data Presentation
* Networking
* Trigger level
* Sound/LED
* Time
* Access Control
* Update

Data Presentation
^^^^^^^^^^^^^^^^^^^^
The settings here will affect all graphs.
The X- and Y-Axis font size as well as the graph line width can be configured here.
Furthermore, the detected photons can be normalized to photons per 1 second (Hz). Note, this setting does not affect the counts recording (see, :ref:`real-time-monitor`) to keep the recorded file consistent.

Networking
^^^^^^^^^^^^^^^^^^^^
The networking tab allows to configure the network access to the WebSQ driver and it is in detailed explained in :ref:`network-setup`.

Trigger Level
^^^^^^^^^^^^^^^^^^^^
The WebSQ driver needs to convert the analog pulses from the SNSPDs to a digital signal for counting. This is done by choosing the appropriate trigger level.
If the analog signal crosses on its rising edge the trigger level a digital pulse is generated. Generally, a good trigger level is at half the peak value.
The peak value can be easily found by rising the trigger level until no photons are register anymore. Let's assume this happens at 630 mV. In that case set the trigger level to 315 mV.
Repeat this process for all detector channels.
Note, that the internal counters were specially optimized for high speed. They can count up to 2 GHz and have therefore a negligible dead time of only 500 ps.

Sound/LED
^^^^^^^^^^^^^^^
The sound tab allows you to choose the type of sound (Square, Sine, Sawtooth, Triangle) and the rollover frequency.
In case your diver is equipped with a LED button you can also dim the LED here for the least light pollution in your lab.

Time
^^^^^^^^^^^^^^
Allows to set the time and timezone. The time is used for time-stamping all the generated files and their entries.

Access Control
^^^^^^^^^^^^^^^^^^
Allows to change the username and password.

Update
^^^^^^^^^^^^^^^^^
Upload and install an update zip package. The update may take several minutes. Never switch off the driver during update as it might break the system.

.. _fig_update-3:
.. figure::  ./graphics/manual_screenshots/Set_update-3.png

    Window to upload and install a new software version.


Help
---------------------------
In the help tab you can browse or download the manual, access sample code how to communicate with the WebSQ driver, and review the license of the installed software.

Advanced Settings
---------------------------

There is a hidden configuration menu to change system settings only needed to be calibrated at the factory.
However, as we are all adults, we describe their functionality here as we want to keep the system as open and configurable as possible.

The advanced settings can be reached by entering driver_ip_address/advanced_settings in your browser's address field.

In the following only parameters which are not self-explanatory are described:

Settings
^^^^^^^^^^^^^^^^^^^^^^^^^^

# of Detectors
  Number of channels present in the system. When changed wait 1 minute before restart to make sure that the settings have been saved.

Latch time
  Time a latched detector is switched off to put it back to normal operation.

Simulation Mode
  Emulates the detection system. Useful for showing the driver's capabilities without a system connected at conferences/shows.

Firmware
  Firmware version of the internal driver card.


Resistors
^^^^^^^^^^^^^^^^^^^^^^^^^^

The bias currents are generated by a voltage applied to the bias resistors.
The resistor values here need to correspond with the actual built in resistors to enable the software to calculate the bias currents.

Trigger
^^^^^^^^^^^^^^^^^^^^^^^^^^

Trigger level to allow the driver to detect a photon.
A small part of the detected signal is tabbed and fed to a high-speed comparator which is capacitively coupled.
A resistor divider network pulls to the tabbed signal to about 640 mV. As the resistors' value vary slightly
the offset needs to be calibrated. Also the trigger gain, the fraction of the tabbed signal to the set trigger level, has to be calibrated. Standard value 0.325.

Calibration procedure:

#. On driver_ip_address/index change the trigger level till your have maximal dark counts.
#. Change the Trigger Level Offset in advanced_settings till the trigger level shows highest counts at zero.
#. Repeat 1. and 2. until the count rates are the highest for zero trigger. Then the offset level is calibrated correctly. Repeat for each detector.
#. Take an oscilloscope and measure the pulse hight of the SNSPD signal.
#. Increase the trigger level until no counts are detected anymore. This level corresponds to the pulse peak hight.
#. Change the trigger gain and repeat 5. till the counts drop-off happens at the measured (4) amplitude. Repeat for each detector.
#. The trigger level is calibrated correctly.

Voltage Latch
^^^^^^^^^^^^^^^^^^^^^^^^^^

Trigger level for latch detection.
When an SNSPD does not return it self to the superconducting state, it is said to have "latched".
To detect a latch we monitor the voltage over the SNSPDs. When they are not superconducting anymore the voltage drop is non zero anynore.
The Latch Level describes which SNSPD voltage should trigger a detected latch. In that case the detector will be power off for a short amount of time.

Frequency Latch
^^^^^^^^^^^^^^^^^^^^^^^^^^

Experimental feature: A latch detect will be triggered if the count rate of a detector falls below or above a certain frequency.

Monitor Bias Voltage
^^^^^^^^^^^^^^^^^^^^^^^^^^

Set Bias Voltage (V)
  Overwrites the bias current calculation. The biasing circuitry will be powered by the specified voltage.
  Useful for connection tests.

Monitor Bias Voltage (V)
  Shows the measured voltage across the SNSDPs. This voltage is used for latch detection.

Temp Diode
^^^^^^^^^^^^^^^^^^^^^^^^^^

Temp. Avrg. Factor
  Value between 0 and 1.
  Each temperature reading is added by a fraction of 1-Averaging Factor to the averaged temerature value.
  That means, a Temp. Avrg. Factor of 0 does not average at all. And a Temp. Avrg. Factor of 1 does not add new data.

Temp. Diode (V)
  Voltage measured across the temperature diode.

Temp. Diode (K)
  Temperature calculated based on linear interpolation between the data points in the calibration file.

Bias Voltage Resistor
  Voltage across the bias voltage resistor used for a PID feedback loop to maintain an accurate bias current.

Set Bias Current
  The temperature diode's bias current.

Cali Points
  Used to shift the calibration file by hand. Legacy.


Temp Cali Upload
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Tab to upload the temperature diode's calibration file.


Board
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Shows the history of the DAQ card temperature and shows the maximal recordered temperature.

Manage Config
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Download/Upload system configuration file.
This file contains all the settings (without the temperature calibration files) of the whole system.
Ideal for system setting backup.

Reset
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Don't do it if you have not taken a system backup under Manage Config.
Completely overwrites all system specific settings by standard values not necessarily corresponding to your system configuration!
