Installation

We recommend starting with our Connector Factory cookiecutter. To verify your installation, you can run the connector and start the SiLA Browser locally. Refer to the SiLA Browser guide on GitLab for further instructions.

Prerequisites

Before getting started your first connector, ensure you have the following prerequisites installed on your system:

• Python 3.10+: Ensure that Python 3.10 or later is installed. We suggest the most recently released version of CPython for the best feature coverage and highest security. You can download Python from python.org.
• Git: Ensure that Git is installed for version control. You can download the latest version from git-scm.com.
• pipx: Ensure that pipx is installed to manage your global python environment and dependencies. This can be installed using pip after successfully installing Python:
  Terminal

  pip install pipx
  pipx ensurepath
  

• Cruft: Ensure that cruft is installed to create boilerplate for new connector projects. This can be installed using pipx to make it available system-wide:
  Terminal

  pipx install cruft
  

  Using uv? You can skip installing pipx entirely and run cruft directly with uv: uvx cruft create https://gitlab.com/unitelabs/cdk/connector-factory.git. Jump straight to Setup your Environment Manager.

0. Setup your Environment Manager

Our connector-factory supports three popular environment/package managers: uv, hatch, and poetry. Check out our Library Comparison of the three tools to learn more about the differences and decide which tool is right for you.

pipx install uv

pipx install hatch
hatch config set dirs.env.virtual .venv

pipx install poetry
poetry config virtualenvs.in-project true

If you are using uv or hatch and plan to use the Omnibus for the device communication layer of your connector, you will need to set up a .netrc file in your home directory with your GitLab credentials. This can be done by running the following command:

• On Linux or macOS:
  Terminal

  cat <<EOF > ~/.netrc
    machine gitlab.com
    login <username>
    password <PAT>
  EOF
  

• On Windows:
  Terminal

  @"
  machine gitlab.com
  login <username>
  password <PAT>
  "@ | Out-File -FilePath "$env:USERPROFILE\.netrc" -Encoding ASCII
  

Note that the <username> placeholder should be replaced with your GitLab username and <PAT> placeholder should be replaced with your GitLab Personal Access Token (PAT).

1. Generate a New Connector Project

Use Cruft to create a new connector project:

cruft create https://gitlab.com/unitelabs/cdk/connector-factory.git

It prompts you to enter some basic information about your project, such as:

• Connector Name:: The name of your instrument to connect.
• Description: A description of the instrument's main purpose.
• Communication Type: The hardware communication protocol (e.g., none, Serial, USB, TCP, UDP).

This creates a structured project directory. The exact layout depends on the communication type you chose:

├── project-name
  ├── src/unitelabs/package_name
    ├── __init__.py
    └── __main__.py
  ├── tests
    ├── __init__.py
    ├── conftest.py
    └── test_version.py

├── project-name
  ├── src/unitelabs/package_name
    ├── __init__.py
    ├── __main__.py
    └── io
      ├── __init__.py
      └── package_name_protocol.py
  ├── tests
    ├── __init__.py
    ├── conftest.py
    └── test_version.py

2. Generate the Configuration File

Before starting the connector, you must generate a configuration file. Navigate into your project directory and run the config create command:

cd project-name
uv run config create --app unitelabs.${your_package_name_here}:create_app

cd project-name
hatch run config create --app unitelabs.${your_package_name_here}:create_app

cd project-name
poetry run config create --app unitelabs.${your_package_name_here}:create_app

This creates a config.json file in the current directory with default settings. See the Configuration Guide for more details on customizing your configuration.

3. Verify the Installation

Run the connector to ensure everything is working:

uv run connector start --app unitelabs.${your_package_name_here}:create_app -v

hatch run connector start --app unitelabs.${your_package_name_here}:create_app -v

poetry run connector start --app unitelabs.${your_package_name_here}:create_app -v

After starting the connector, you should see output similar to this in your terminal:

INFO:     Starting SiLA 2 server...
INFO:     Server listening on 0.0.0.0:50052
INFO:     Registered feature: de.unitelabs.feature.AwesomeInstrument (1 command, 0 properties)
INFO:     Connector ready

The exact feature name and port will match your connector's configuration. If you see Connector ready, your environment is set up correctly. You can then verify it in the SiLA Browser — it should appear as a discovered device on the local network.

Next Steps

With your environment set up, you can proceed to modify and enhance the existing connector. Check out our Walkthrough for a comprehensive guide to connector development.