Installation, Activation and Upgrading

Requirements

To install htf, a recent version of CPython 3 is required. Recent and actively developed versions of python can be found here. htf supports all Python versions with feature and bugfix status at the minimum. Only 64 bit machines are supported.

htf is tested on Microsoft Windows and all Linux versions that support manylinux wheels. It also runs on Raspberry Pi.

Wheels for Python 3 on Linux are shipped in recent manylinux formats.

We host our own pypi server.

For further information regarding the support of your specific project requirements, please contact contact our Support.

Installation on Windows

If Python is not already installed, please download and install Python using the official CPython installers or use a CPython distribution of your choice, e.g. WinPython.

It is recommended to install Python in the typical paths, e.g. C:\Python312\ for Python 3.12 respectively.

If you want to install htf via pip, you need to add the Scripts folder of the Python distribution to your %PATH% environment variable (there is an option in the installer). pip is shipped with recent Python Windows distributions.

Installation on Linux

On most Linux distributions, at least one version of Python should be installed by default. Since 2020, this version should be Python 3.

pip can be installed by installing the packages python3-pip for Python 3.12, respectively. There are no other dependencies that need to be installed on Linux.

On Ubuntu for example, all dependencies should be satisfied using:

sudo apt install python3-pip

Installation on Raspberry Pi OS

You can easily install HILSTER Testing Framework on a Raspberry Pi OS using the 64 bit installation image available at downloads page.

Installation in a virtual environment

It is generally recommended to separate project dependencies into different virtual environments.

More information about setting up and using virtual environments on Linux can be found in the python-guide and for Windows in the virtualenv docs.

It is recommended to use the virtualenvwrapper package, which provides functions that allow for a convenient handling of virtual environments. Further information can be found in the virtualenwrapper docs.

There is also a Windows port called virtualenvwrapper-win.

Installation using Anaconda

Alternatively Anaconda can be used as a multi-platform Python-Platform. Installers for Windows and Linux are provided by Anaconda. It is pre-packaged with multiple libraries especially from the data science community. Before moving on please download and install Anaconda on your system.

After the base install it is again recommended to separate project dependencies into different virtual environments. You can create a conda environment using the Anaconda Prompt:

conda create --name environment_name python
conda activate environment_name

Further references to the Anaconda Prompt can be found in the Anaconda docs.

You can then proceed to install htf via pip.

Installation of htf via pip

Given that Python is properly set up and the virtual environment of your choice is activated, you can simply install htf using pip:

pip install -i https://pypi.hilster.io htf[full]

To install the community-version accordingly, run

pip install -i https://pypi.hilster.io htf-community

Herein -i https://pypi.hilster.io adds the HILSTER python package repository to the search index of pip so that the HILSTER packages can be discovered.

Depending on your installation, you might have to replace pip with pip3.

Installation options

htf comes with submodules that can be installed manually or using installation options.

Installation options are put behind the package in the pip prompt.

For example

pip install -i https://pypi.hilster.io htf

only installs the core of htf.

pip install -i https://pypi.hilster.io htf[full]

installs all possible options.

There is an installation option for all submodules, e.g. the option for htf-modbus is [modbus] and for htf-hart you can use [hart].

Installation options can be combined as a coma-separated list:

pip install -i https://pypi.hilster.io htf[modbus,hart]

installs htf-modbus and htf-hart.

Another option is htf[oser] to install oser directly.

Installation behind a corporate proxy

If you are behind a corporate proxy, there are several ways to tell pip about the proxy url and your credentials.

The simplest solution is to just use the --proxy argument

pip install -i https://pypi.hilster.io --proxy=http://<username>:<password>@<host>:<port> htf

If you want to persist the proxy settings, it is recommended to store them in the pip configuration file pip.ini, which is stored in the pip folder in your home directory.

[global]
proxy = http://<username>:<password>@<host>:<port>

Another solution is use the environment variable https_proxy.

On Linux enter:

export https_proxy=https://<username>:<password>@<host>:<port>

and on Windows enter:

set https_proxy=https://<username>:<password>@<host>:<port>

and continue with the installation without the --proxy option.

Installing a validated version of htf

To install a validated htf version you need to install a validated combination of Python and the htf-validated package.

A list of validated htf versions and Python versions can be found in the table in documentation of htf-validated.

htf-validated will check the system environment automatically when it runs. It will fail if there is any kind of deviation from the validated environment.

On Linux we recommend to use pyenv and you can also use Docker.

On Windows we recommend to use pyenv-win but you can also install the Python version directly or you can use Docker.

To install the latest validated version of htf, run the following command using the validated Python version:

pip install -i https://pypi.hilster.io htf-validated

To install a specific validated version, run:

pip install -i https://pypi.hilster.io htf-validated==4.1.0

Activation

HILSTER’s license server is used for remote activation.

Activation is not needed if you use the community edition, since a license is already included.

To activate non-community versions of the software, you need one or more activation keys that HILSTER sent you.

An activation key consists of 16 upper case letters in 4 groups concatenated by dashes.

hlm activate ABCD-EFGH-IJKL-MNOP

You can also activate more then one activation key at a time.

hlm activate ABCD-EFGH-IJKL-MNOP QRST-UVWX-YZAB-CDEF  # ...

Activation creates a license that is stored locally.

To renew the licenses once activated, simply run

hlm renew

When you are behind a proxy, you have to set the environment variable https_proxy like in the installation process.

Every virtual environment has to be activated separately.

Check installation

To list your licenses, run

hlm list

If htf prints a version, it is unlockable

htf version  # prints the version

Upgrading

To upgrade add the -U option:

pip install -i https://pypi.hilster.io -U htf

If you are using a proxy you must add the --proxy option or set environment variables like described above.

Installing a specific version

To install a specific version use

pip install -i https://pypi.hilster.io htf==2.0.0

for example.

If you are using a proxy you must add the --proxy option or set environment variables like described above.

Automatic check for updates

htf checks for available updates at the end of a test run automatically. This can be disabled by setting the HTF_DISABLE_UPDATE_CHECK environment variable.

On Linux enter:

export HTF_DISABLE_UPDATE_CHECK=1

and on Windows enter:

set HTF_DISABLE_UPDATE_CHECK=1

Installing the community version

To install the community version, run

pip install -i https://pypi.hilster.io htf-community

Manual activation is not needed because the community license is already included and the activation will be performed automatically.

Make sure to use a recent Python version to install the latest version for htf-community. Read installation requirements for more information.

The available wheels and supported Python versions can also be found on HILSTER’s PyPI server, too.