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 Safety & Compliance.

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.
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) Time Tagger Lab,
- 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 on how to obtain an offline license.

The directory used to store the software license and application data can be customized; see Application data directory.

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

Graphical user interface: launch the Time Tagger Lab. Please refer to the Time Tagger Lab 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 Programming Languages 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:
```
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 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:
```
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 on how to obtain an offline license.

Time Tagger Lab

Time Tagger Lab 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 Time Tagger Lab section. Here, you can follow simple instructions to enable the Time Tagger’s internal test signal and measure a cross correlation between two channels.

Launch the Time Tagger Lab 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 $\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

Installation

deb/RPM package

Download and install the package for your Linux distribution from our downloads site. 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 on how to obtain an offline license.

The directory used to store the software license and application data can be customized; see 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 Programming Languages section for further details.

Python package

Install the Python module for the Time Tagger in your local environment (see venv documentation) using the command:
```
pip install Swabian-TimeTagger
```
Create a udev rule granting user access to Swabian Instruments devices (vendor ID 151f):
```
# 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:
```
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 on how to obtain an offline license.

Now you are ready to make a first measurement. Please refer to Programming Languages section for further details.

Custom Python installation

Install NumPy (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.

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

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 Usage Statistics Collection)

To use a custom directory, set the TIMETAGGER_CONFIG_DIR environment variable to the desired path before creating a Time Tagger instance or launching Time Tagger Lab. 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:

[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

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 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). 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.