With an executable
Connectors are distributed as self-contained executables that bundle their own Python runtime, so you can run one on any machine without installing GroundControl or Python. This page covers how to start the executable and the commands you can run through it.
systemd service, follow the Headless install guide.Pick the right executable
Executables are built per device and per platform, following the naming scheme unitelabs-<device-name>-<platform>-<version>:
| Platform | <platform> | Example |
|---|---|---|
| Windows (x86_64) | x86_64-pc-windows-msvc | unitelabs-microlab-star-x86_64-pc-windows-msvc-0.5.0.exe |
| Linux (x86_64) | x86_64-unknown-linux-gnu | unitelabs-microlab-star-x86_64-unknown-linux-gnu-0.5.0 |
| Linux (ARM64, e.g. Raspberry Pi) | aarch64-unknown-linux-gnu | unitelabs-microlab-star-aarch64-unknown-linux-gnu-0.5.0 |
| macOS (Apple Silicon) | aarch64-apple-darwin | unitelabs-microlab-star-aarch64-apple-darwin-0.5.0 |
--start-cmd additionally requires the --app option pointing at the connector's app factory, e.g. --start-cmd "config create --app unitelabs.<device_name>:create_app". Note that <device_name> uses underscores here, e.g. unitelabs.microlab_star:create_app for the Microlab STAR.Start the connector
Run the executable directly to start the connector with its default configuration (config.json in the current directory):
# Make the file executable once after downloading
chmod +x unitelabs-<device-name>-<platform>-<version>
./unitelabs-<device-name>-<platform>-<version>
.\unitelabs-<device-name>-x86_64-pc-windows-msvc-<version>.exe --start-cmd "connector start --app unitelabs.<device_name>:create_app"
The connector reads config.json from the working directory. To generate one first, or to point at a different file, use the start commands below.
Choose a start command
By default the executable runs connector start. The --start-cmd flag lets you run any of the connector's CLI commands through the same binary.
For example automatically generating a config.json, inspecting the config documentation or starting the connector.
# Generate a default config.json in the current folder
./unitelabs-<device-name>-<platform>-<version> --start-cmd "config create"
# Show the resolved configuration
./unitelabs-<device-name>-<platform>-<version> --start-cmd "config show"
# Start the connector explicitly (the default)
./unitelabs-<device-name>-<platform>-<version> --start-cmd "connector start"
# Generate a default config.json in the current folder
.\unitelabs-<device-name>-x86_64-pc-windows-msvc-<version>.exe --start-cmd "config create --app unitelabs.<device_name>:create_app"
# Show the resolved configuration
.\unitelabs-<device-name>-x86_64-pc-windows-msvc-<version>.exe --start-cmd "config show --app unitelabs.<device_name>:create_app"
# Start the connector explicitly (the default)
.\unitelabs-<device-name>-x86_64-pc-windows-msvc-<version>.exe --start-cmd "connector start --app unitelabs.<device_name>:create_app"
These are the same connector and config commands you would run from source (see From source) for what each command does and how to configure logging, the SiLA server, and the cloud connection.
--start-cmd "connector start -vvv" in older guides. The -v/--verbose flag is deprecated and will be removed in a future version. Configure the log level through the logging section of your config instead (see Logging).Use the connector
With your connector running, you can interact with your instrument in three ways:
- GroundControl — read values, trigger actions, and monitor activity directly from the edge app.
- UniteLabs Platform — view, inspect, and operate the connector from the Platform UI, and add it to workflows.
- SDK & REST API — control the connector programmatically: discover services, explore modules and actions, and subscribe to live data.