*************************
Installation Instructions
*************************

This section explains how to install the Time Tagger Software on Windows and Linux.
Before installing and operating the Time Tagger, users are strongly advised to follow the guidelines
for proper handling. For detailed information on operating conditions and limits, please refer to
:doc:`Safety & Compliance </legal/index>`.

.. admonition:: Time Tagger software download

    https://www.swabianinstruments.com/time-tagger/downloads/


Windows
#######

Time Tagger software requires Windows 10 or higher (64 bit).
Windows on Arm (ARM64) is currently not supported. Please use a Windows x64 (Intel/AMD) PC.
For Windows 10, we provide full support only for those versions that are still actively supported by Microsoft.
Older versions, while untested, might still work.

Installation
************

Windows installer
=================

#. Download the installer from our `downloads site <https://www.swabianinstruments.com/time-tagger/downloads/>`_.

#. Run the installer and follow the instructions. This installs:

   - the USB drivers,

   - C++, Python, .NET, C#, LabVIEW, and MATLAB libraries,

   - the graphical user interface (GUI) |ttlab-name|,

   - the examples,

   - the offline documentation.

#. Connect your Time Tagger.

#. We recommend connecting your computer to the internet once you run the Time Tagger software.
   This will make sure that the software can request the license needed to use the `Time Tagger Virtual`
   functionality to replay the recorded data, without having the Time Tagger connected.
   This functionality can always be used when a hardware time tagger is connected to the PC.
   If the PC cannot be brought online even once, but you need the license, please see the
   `related FAQ <https://www.swabianinstruments.com/knowledge/base/time-tagger-setup/resolving-license-acquisition-errors/>`_
   on how to obtain an offline license.

   The directory used to store the software license and application data can be customized;
   see :ref:`application-data-directory`.

Now you are ready to make a first measurement. You can either use:

- Graphical user interface: launch the |ttlab-name|. Please refer to the :ref:`TTLab` paragraph below.

- Programming languages: use the examples installed with the software
  (see your installation’s ``examples/<language>/`` folder) to get familiar with the Time Tagger API.
  Please refer to :doc:`Programming Languages </gettingStarted/ProgrammingLanguages>` section for further details.

Python package
==============

The Time Tagger Python package can also be installed from PyPI without using
the full Windows installer. This installs the Python module only. To access a
physical Time Tagger over USB, the Opal Kelly USB driver must also be available
on the system.

#. Install the Python module for the Time Tagger in the Python environment you
   want to use:

   .. code-block:: bash

       pip install Swabian-TimeTagger

#. To communicate with a physical Time Tagger over USB, the Opal Kelly USB driver
   must be installed. If it is not already installed, please download and install the
   `Opal Kelly FrontPanelUSB driver <https://pins.opalkelly.com/downloads>`_
   for Windows.

   Afterward, connect the Time Tagger to the PC. If it was already
   connected during the installation, disconnect and reconnect it so that Windows
   re-enumerates the USB device.

#. In Device Manager, the device should appear under ``FrontPanel devices``. If it
   appears under ``Other devices`` as an Opal Kelly XEM device, open the
   device properties and select ``Driver`` -> ``Update Driver`` -> ``Search
   automatically for drivers``. After successful driver installation, the device
   should be listed under ``FrontPanel devices``.

#. Connect to the Time Tagger:

   .. code-block:: python

       from Swabian import TimeTagger

       tagger = TimeTagger.createTimeTagger()

   We recommend connecting your computer to the internet when creating the
   Time Tagger once. This allows the software to request the license needed to
   use the Time Tagger Virtual functionality to replay recorded data without
   having the Time Tagger connected. This functionality can always be used when
   a hardware Time Tagger is connected to the PC.
   If the PC cannot be brought online even once, but you need the license,
   please see the `related FAQ <https://www.swabianinstruments.com/knowledge/base/time-tagger-setup/resolving-license-acquisition-errors/>`_
   on how to obtain an offline license.

.. _TTLab:

Time Tagger Lab
***************

|ttlab-name| is the |GUI| application for Windows operating systems.
It is designed to perform standard measurements quickly and to get an interactive experience with your Time Tagger.
For a step-by-step walkthrough, see the :doc:`Time Tagger Lab </gettingStarted/GettingStartedTTLab>` section.
Here, you can follow simple instructions to enable the Time Tagger's internal test signal and measure
a :ref:`cross correlation<api.Correlation>` between two channels.

Launch the |ttlab-name| application and select your device,
switch to ``Detailed View``, and enable the internal test signal on inputs 1 and 2 by checking the boxes on the very right column.
You should see live count rates. Open ``Creator (F2)``, choose ``Bidirectional histogram – Correlation``,
set ``Reference = 1`` and ``Click = 2``, then add the measurement and press ``Play``.
A Gaussian peak should be displayed. You can zoom in using the controls on the plot.
The detection jitter of a single channel is :math:`\frac{1}{\sqrt{2}}` times the standard deviation
of this two-channel measurement (the |FWHM| of the Gaussian peak is 2.35 times its standard deviation).

.. _linux:

Linux
#####

Installation
************

deb/RPM package
===============

#. Download and install the package for your Linux distribution from our
   `downloads site <https://www.swabianinstruments.com/time-tagger/downloads/>`_.
   The package installs the Python and C++ libraries including the examples and offline documentation.

#. Connect your Time Tagger.

#. We recommend connecting your computer to the internet once you run the Time Tagger software.
   This will make sure that the software can request the license needed to use the `Time Tagger Virtual` 
   functionality to replay the recorded data, without having the Time Tagger connected.
   This functionality can always be used when a hardware time tagger is connected to the PC.
   If the PC cannot be brought online even once, but you need the license, please see the
   `related FAQ <https://www.swabianinstruments.com/knowledge/base/time-tagger-setup/resolving-license-acquisition-errors/>`_
   on how to obtain an offline license.

   The directory used to store the software license and application data can be customized;
   see :ref:`application-data-directory`.

Now you are ready to make a first measurement. You can use:

- Programming languages: use the examples installed with the software
  (see your installation’s ``examples/<language>/`` folder) to get familiar with the Time Tagger API.
  Please refer to :doc:`Programming Languages </gettingStarted/ProgrammingLanguages>` section for further details.

Python package
==============
#. Install the Python module for the Time Tagger in your local environment (see `venv documentation <https://docs.python.org/3/library/venv.html>`_)
   using the command:

   .. code-block:: bash

       pip install Swabian-TimeTagger

#. Create a udev rule granting user access to Swabian Instruments devices (vendor ID 151f):

   .. code-block:: bash

       # Create /etc/udev/rules.d/60-swabian.rules with the correct permissions
       echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="151f", MODE="0666"' | sudo tee /etc/udev/rules.d/60-swabian.rules >/dev/null
  
   This rule matches all USB devices with vendor ID 151f and sets their permissions
   to be readable/writable by any user on the system (MODE="0666").

   .. warning::

    MODE="0666" makes the device accessible to all local users.
    If you prefer a tighter policy, you can restrict access to a specific group (e.g. plugdev).

#. Reload udev rules so new devices plugged after this step are granted access:

   .. code-block:: bash

       sudo udevadm control --reload-rules

#. Connect your Time Tagger.

#. We recommend connecting your computer to the internet when creating the
   Time Tagger once. This allows the software to request the license needed to
   use the Time Tagger Virtual functionality to replay recorded data without
   having the Time Tagger connected. This functionality can always be used when
   a hardware Time Tagger is connected to the PC.
   If the PC cannot be brought online even once, but you need the license,
   please see the `related FAQ <https://www.swabianinstruments.com/knowledge/base/time-tagger-setup/resolving-license-acquisition-errors/>`_
   on how to obtain an offline license.

Now you are ready to make a first measurement.
Please refer to :doc:`Programming Languages </gettingStarted/ProgrammingLanguages>` section for further details.

.. _linux-build-python:

Custom Python installation
--------------------------

* Install :doc:`NumPy <numpy:user/index>` (e.g. ``pip install numpy``), which is required for the Time Tagger libraries.
* The Python libraries are installed in your default Python search path: ``/usr/lib/pythonX.Y/dist-packages/`` or ``/usr/lib64/pythonX.Y/site-packages/``.
* The examples can be found within the ``/usr/share/timetagger/examples/python/`` folder.

You can compile a Python module for custom Python installations in the following way:

The source of the Python wrapper ``_TimeTagger.cxx`` is provided in ``/usr/lib64/pythonX.Y/site-packages/``.
For building the wrapper, the GNU C++ compiler and the development headers of Python and numpy need to be installed.
The resulting ``_TimeTagger.so`` and the high-level wrapper ``TimeTagger.py`` relay the Time Tagger C++ interface to Python.

.. code-block:: bash

    PYTHON_FLAGS="`python3-config --includes --libs`"
    NUMPY_FLAGS="-I`python3 -c \"print(__import__('numpy').get_include())\"`"
    TTFLAGS="-I/usr/include/timetagger -lTimeTagger"
    CFLAGS="-std=c++17 -O2 -DNDEBUG -fPIC $PYTHON_FLAGS $NUMPY_FLAGS $TTFLAGS"

    g++ -shared _TimeTagger.cxx $CFLAGS -o _TimeTagger.so

.. _application-data-directory:

Application data directory
##########################

The Time Tagger software stores the local software license and other user-specific data
in an application data directory. The default location depends on the operating system:

- **Windows**: ``%APPDATA%\Swabian Instruments\Time Tagger``
  (typically ``C:\Users\<username>\AppData\Roaming\Swabian Instruments\Time Tagger``)
- **Linux**: ``~/.timetagger``

This directory is created automatically on first use and contains the following Time Tagger-related files:

- ``License.txt``: the local software license for *Time Tagger Virtual*
- ``LicenseRequest.txt``: a request file used during license acquisition
- ``TelemetryDatabase.bin``, ``TelemetrySettings.bin``: usage statistics data
  (see :doc:`UsageStatistics`)

To use a custom directory, set the ``TIMETAGGER_CONFIG_DIR`` environment variable to the
desired path before creating a Time Tagger instance or launching |ttlab-name|.
The directory is created automatically if it does not exist.
This is useful in cases where the default application data location is unsuitable,
for example on shared lab computers, in controlled deployment environments,
or when running the Time Tagger library from a systemd service with a dedicated service user
that has no writable home directory. In that case the service unit can set the variable explicitly:

.. code-block:: ini

    [Service]
    User=timetagger-service
    Environment=TIMETAGGER_CONFIG_DIR=/var/lib/timetagger-service/appdata

.. warning::

    Existing files are not migrated automatically when switching to a custom directory.

.. _offline_installation:

Offline installation
####################

The TimeTagger software may require an internet connection to download necessary components and, as such,
installation with network access is recommended.
The following must be kept in mind when access to a network upon installation is limited.

License retrieval
*****************

If you require an hardware license upgrade, an internet connection is required
to download the license used to enable the hardware channels.
After the license has been retrieved, the TimeTagger and its software
may be used offline on this computer from that point onward.

In some cases, it may not be possible for a computer to be connected to the internet under any circumstances.
In this case, a license may be manually requested by contacting support@swabianinstruments.com.

Windows installer
*****************

In addition to the above, the Windows TimeTagger installer may require an internet connection
to download and authenticate necessary components of the software.

.NET Desktop Runtime
********************

To use TimeTaggerLab, the .NET Desktop Runtime version 10 is required.

The installer will detect the runtime present on the computer and attempt to download the latest required version.
If it is unable to do so, the installation will proceed but the TimeTaggerLab application
will be blocked until a suitable run time is installed.

To manually install the .NET Desktop Runtime,

 * `download the installer from the official Microsoft website <https://dotnet.microsoft.com/en-us/download/dotnet/10.0>`_ using a computer with network access,
 * transfer the downloaded installer to the offline computer (e.g. via a USB pen-drive),
 * install the software by following the instructions.

After successful installation, TimeTaggerLab should be ready to use.

Trusted certificate authorities
*******************************

The TimeTagger software ships with signed USB drivers. To verify the authenticity of the signatures,
`Windows validates the drivers' signature against a root trusted certificate authority (CA) <https://learn.microsoft.com/en-us/windows-server/identity/ad-cs/certificate-trust>`_.
The trust lists are updated regularly so without internet access a computer cannot fetch updates to the certificate trust list.
In this scenario, Windows will refuse to install USB drivers and the installation procedure will fail.

To update the trusted root certificates, you must either update your Windows installation over the network or contact 
your system administrator `to set up trusted root certificates updates manually on Windows <https://learn.microsoft.com/en-us/windows-server/identity/ad-cs/configure-trusted-roots-disallowed-certificates#configure-a-file-or-web-server-to-download-the-ctl-files>`_.