Installation & Setup

The QHarbor platform consists of two components:

DataQruiser App: our graphical user interface to visualize and interact with your data. You can download and install the application from DataQruiser App Releases.
the qDrive Package: allow you to interact with your measurement data and synchronizing it with the DataQruiser app from python. Below the installation details.

Installing the qDrive package

The minimum Python version is Python 3.7.

It is highly recommended to install the qDrive package in a separate environment to prevent conflicts with other Python packages, especially if older measurement software is in use.

Python environment setup

To create a new environment and install the qDrive package, open the Anaconda prompt and run:

conda create -n qdrive_env python=3.11

Activate the environment:

conda activate qdrive_env

Note

If you wish to install qDrive in an existing environment, you can test its compatibility with the other packages in that environment by cloning the environment, and installing qDrive in the cloned environment:

conda create --name myclone --clone my_measurement_env

After installation, ensure compatibility by importing your commonly used packages.

Spyder users : If you are installing qDrive in the same environment where spyder is installed, ensure Spyder is up to date (i.e. uses PyQt5 >= 5.15.0) to avoid compatibility issues.

Installation

Once your environment is active, install the qDrive package by running:

pip install qdrive

Note

If you encounter errors during installation in an existing environment, it may be due to package dependencies. To resolve these, update the relevant package by running:

pip install -U package_that_needs_an_update

Running the Synchronization Agent

The qDrive package manages data synchronization via a process that starts automatically when the package is imported in Python (when you run import qdrive).

To start the synchronization agent GUI and log in, run the following command in the environment where qdrive is installed:

python -c "import qdrive; qdrive.launch_GUI()"

Upon login, a persistent login session is established, so you won’t need to log in again unless you log-out.

To log-out click the log-out button in the GUI, or use the command qdrive.logout() in Python.

To stop or start the synchronization agent, click the Kill/start sync button in the GUI, or use the command qdrive.restart_sync_agent() in Python.

Note

You can also log in directly from a Python kernel/console/jupyter-notebook from the environment where qdrive is installed running:

import qdrive
qdrive.authenticate_with_console()

When working on a server, you can also authenticate with an API-Token.

Using API-Tokens for Authentication

When working on a server, with no graphical environment, you can log in using an API-Token.

An API-Token can be created in the DataQruiser app:

Open the DataQruiser app.
Click on the account icon (👤) in the top right corner.
Navigate to the “API-Tokens” section.
Click the “+” button to generate a new token.
Enter a descriptive name for your token (e.g., “Synchronization server token”).
Copy the generated token immediately - it will only be shown once.

Now it is possible to authenticate on the server using your API-Token:

from qdrive import login_with_api_token

login_with_api_token('your_api_token@qharborserver.nl')

# Verify the authentication was successful
from qdrive.scopes import get_scopes
print(f"Successfully authenticated. You have access to {len(get_scopes())} scopes.")

Tip

The API-Token is a secret key that should be kept confidential. We do not recommend storing it in any files. If you suspect your API-Token has been compromised, immediately revoke it in the DataQruiser app.

Updating the qDrive package

If the synchronization GUI is open, close it first.

To update qDrive, activate the environment where it was installed and run the following command to update and restart the synchronization agent:

pip install qdrive --upgrade
python -c "import qdrive; qdrive.restart_sync_agent(); qdrive.launch_GUI()"