Headless install

Connectors are distributed as self-contained executables that bundle their own Python runtime. You can run them directly on any Linux machine without installing GroundControl or Python. This is the typical setup for:

• Raspberry Pi devices co-located with instruments
• Headless Linux servers in the lab network
• Environments where a GUI is not practical

For workstations and lab PCs with a display, GroundControl is the easier path.

Get the connector executable

Contact your UniteLabs representative or download the connector from the UniteLabs connector registry. Executables are named:

unitelabs-<device-name>-<platform>-<version>

For example, on a Raspberry Pi 4 (64-bit):

unitelabs-microlab-star-aarch64-unknown-linux-gnu-0.5.0

Common architecture suffixes:

The commands below use unitelabs-<device-name>-<platform>-<version> as a placeholder — replace it with the file name of the executable you downloaded, and <device_name> with your device, e.g. microlab_star.

Install and configure

1. Place the binary

Create a folder for the connector under /opt/connectors/:

sudo mkdir -p /opt/connectors/<device_name>
sudo cp unitelabs-<device-name>-<platform>-<version> /opt/connectors/<device-name>/
sudo chmod +x /opt/connectors/<device_name>/unitelabs-<device-name>-<platform>-<version>

2. Generate the default config

Run the connector once with the config create command to generate a config.json with all available fields:

cd /opt/connectors/<device_name>
./unitelabs-<device-name>-<platform>-<version> --start-cmd "config create"

This writes config.json to the current folder.

3. Edit config.json

Open config.json and fill in the instrument-specific settings — typically the connector's hostname or IP address and port it should run on or instrument specifics such as the serial port (This is not required for the Mircolab STAR as it auto-detects the instrument):

{
  "serial_port": "",
  "sila_server": {
    "hostname": "0.0.0.0",
    "port": 50052,
    "tls": true,
    "name": "Hamilton Microlab STAR",
    ...
  }
}

To connect to the UniteLabs cloud, edit the cloud_server_endpoint block:

{
  "cloud_server_endpoint": {
    "hostname": "<tenant-id>.unitelabs.io",
    "port": 443,
    "tls": true
  }
}

4. Test run

Run the connector directly to verify it starts and connects to the instrument:

./unitelabs-<device-name>-<platform>-<version>

Check the logs for any connection errors. Press Ctrl+C to stop. The default logging config writes a log file in the specified folder in the config.json. For troubleshooting during a headless install, we recommend starting a connector in a more verbose mode that prints the logs to the terminal

./unitelabs-<device-name>-<platform>-<version> --start-cmd "connector start -vvv"

Register as a systemd service

For production use, register the connector as a systemd service so it starts automatically on boot and restarts on failure.

Create the service file

Create /etc/systemd/system/ul-<device_name>.service:

[Unit]
Description=UniteLabs <Device Name>
After=network.target
Wants=network-online.target

[Service]
User=<your-user>
WorkingDirectory=/opt/connectors/<device_name>
ExecStart=/opt/connectors/<device_name>/unitelabs-<device-name>-<platform>-<version>
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start

sudo systemctl daemon-reload
sudo systemctl enable ul-<device_name>
sudo systemctl start ul-<device_name>
sudo systemctl status ul-<device_name>

Common service commands

# List all UniteLabs services
systemctl list-units | grep ul-

# Check logs
journalctl -u ul-<device_name> -f

# Restart after a config change
sudo systemctl restart ul-<device_name>

Back up the service file

Store a copy of the service file alongside the connector binary so the setup can be fully reconstructed from /opt/connectors/ alone:

sudo cp /etc/systemd/system/ul-<device_name>.service /opt/connectors/<device_name>/

Notes

• The connector binary unpacks a Python runtime into a .cache/ directory on first run. This is expected behavior shared across all connectors.
• Each connector must use a unique port for its local SiLA 2 server. By convention, assign ports incrementally (50052, 50053, 50054, …) or use a site-specific range.
• See Network requirements for firewall rules and other security settings.

Example: multi-connector Raspberry Pi setup

For a complete example of multiple connectors running on a single Raspberry Pi, including folder layout, active services, and troubleshooting, see the Raspberry Pi deployment example.