Configuration Files#

This page covers the configuration files used by InstrumentServer: the server configuration file and the listener configuration file.

Server Configuration#

The server configuration file (typically serverConfig.yml) configures instruments, GUI defaults, and networking settings for the InstrumentServer.

Example File#

You can view the example file on GitHub: serverConfig.yml

# Server Configuration File
# ========================
#
# This file configures instruments and GUI defaults for the InstrumentServer.
#
# GLOB PATTERN MATCHING
# ---------------------
# All hide/star/trash configuration lists support glob pattern matching:
#   *           Matches any number of characters
#               Example: "power_*" matches "power_level", "power_offset", "power_max"
#
#   ?           Matches exactly one character
#               Example: "ch?_gain" matches "ch1_gain", "ch2_gain", "chA_gain"
#
#   [seq]       Matches any character in the sequence
#               Example: "trace_[0-3]" matches "trace_0", "trace_1", "trace_2", "trace_3"
#
#   [!seq]      Matches any character NOT in the sequence
#               Example: "param_[!xy]" matches "param_a", "param_z" but NOT "param_x" or "param_y"
#
# You can use exact names or glob patterns in any hide/star/trash list.
#
# From qcodes station config, the first field must be instruments for instruments config
instruments:
  # Name of the instrument
  rr:
    # The class of the instrument
    type: instrumentserver.testing.dummy_instruments.rf.ResonatorResponse
    # If initialize is true, the server will create an instance of this instrument at startup
    initialize: True

  dummy:
    type: instrumentserver.testing.dummy_instruments.generic.DummyInstrumentWithSubmodule
    initialize: true
    # If you want to specify any configuration for the gui, it must be under the gui field.
    gui:
      # Indicates the class of the widget that will be shown when the instrument window is open.
      # Can be either 'generic' or the python class for it
      type: generic
      # any item under kwargs will be passed to the constructor of the widget as kwargs.
      # The following are kwargs specifically for the generic widget
      kwargs:
        # Instance-specific config: These settings apply ONLY to this 'dummy' instance
        # They will be MERGED with gui_defaults for this class (DummyInstrumentWithSubmodule)
        #
        # For this 'dummy' instance, the final merged config will include:
        #   From __default__: [IDN, device_id, timeout] (but IDN is overridden below)
        #   From DummyInstrumentWithSubmodule class: [param*, A] (param* will match param0, param1, etc.)
        #   From this instance: [A, B.ch0, IDN] (below)
        # Final parameters-hide = [device_id, timeout, param*, A, B.ch0, IDN]

        # Any parameters inside parameters-hide will never be loaded or shown.
        parameters-hide:
          - A              # Instance-specific: hide parameter A
          - B.ch0          # Instance-specific: hide submodule parameter
          - IDN            # Instance-specific: explicitly hide IDN (also in __default__)

        # Any parameters inside parameters-star will start being starred.
        parameters-star:
          - param0         # Instance-specific: star param0
          - C              # Merged with class default which also stars C

        # Any parameters inside parameters-trash will start trashed.
        parameters-trash:
          - param1

        # Any methods inside methods-hide will never be loaded or shown.
        methods-hide:
          - C.dummy_function

        # Any methods inside methods-star will start being starred.
        methods-star:
          - A
          - test_func

        # Any methods inside methods-star will start being starred.
        methods-trash:
          - B

  parameter_manager:
    type: instrumentserver.params.ParameterManager
    initialize: True

    gui:
      # By having the parameter manager GUI as the gui type, we can have it directly in the server instead of on a separate window.
      type: instrumentserver.gui.instruments.ParameterManagerGui

# GUI defaults: Class-based configuration that applies to all instances of a given instrument class
# These are merged with instance-specific gui.kwargs configs (instance settings take precedence)
# Merge order: __default__ → ClassName → instance-specific
gui_defaults:
  # __default__ applies to ALL instruments (unless overridden)
  __default__:
    # Hide common parameters across all instruments
    parameters-hide:
      - IDN              # Hide identification parameter
      - device_id        # Hide device ID
      - timeout          # Hide timeout setting

    # Hide common methods across all instruments
    methods-hide:
      - get_idn          # Hide get_idn method
      - snapshot         # Hide snapshot method
      - print_readable_snapshot

  # Class-specific defaults - applies to all instances of DummyInstrumentWithSubmodule
  DummyInstrumentWithSubmodule:
    parameters-hide:
      - param*           # Wildcard: hide all parameters starting with 'param'
      - A                # Hide specific parameter 'A'

    methods-hide:
      - test_*           # Wildcard: hide all methods starting with 'test_'

    # These would be starred by default for all DummyInstrumentWithSubmodule instances
    parameters-star:
      - C

    methods-star:
      - dummy_function

  # Another class example - ResonatorResponse
  ResonatorResponse:
    parameters-hide:
      - calibration_*    # Hide all calibration parameters
      - raw_data         # Hide raw data parameter

    parameters-star:
      - frequency        # Star important parameters by default
      - power

  # Example for a real instrument class
  Keysight_E5080B:
    parameters-hide:
      - power_*          # Hide all power-related parameters
      - if_bandwidth_*   # Hide IF bandwidth parameters

    methods-hide:
      - reset            # Hide reset method
      - clear_status

    parameters-star:
      - start_frequency  # Star the most important parameters
      - stop_frequency
      - center_frequency

# Field for adding broadcasting and listening addresses to the instrument server
networking:
  # Adds additional address to listen to messages received by the server, Example: "192.168.1.1"
  listeningAddress: "192.168.1.1"

  # Adds an address to broadcast parameter changes to, Example: "tcp://192.168.1.1:6000"
  externalBroadcast: "tcp://192.168.1.1:6000"

Instruments Section#

The instruments section defines the instruments that the server will manage. Each instrument is identified by a name (e.g., rr, dummy) and has the following fields:

Field	Description
`type`	The fully qualified Python class path for the instrument (QCoDeS driver)
`initialize`	If `true`, the server creates an instance of this instrument at startup
`address`	(Optional) The network address of the instrument
`init`	(Optional) Additional initialization parameters passed to the instrument constructor
`gui`	(Optional) GUI-specific configuration for the instrument

GUI Configuration#

The gui field within an instrument allows customization of how the instrument appears in the GUI:

Field	Description
`type`	Widget class to use. Can be `generic` or a fully qualified Python class path
`kwargs`	Arguments passed to the widget constructor

Within kwargs, you can configure which parameters and methods are hidden, starred, or trashed:

parameters-hide: Parameters that will never be loaded or shown
parameters-star: Parameters that start as starred (favorites)
parameters-trash: Parameters that start in the trash
methods-hide: Methods that will never be loaded or shown
methods-star: Methods that start as starred
methods-trash: Methods that start in the trash

GUI Defaults Section#

The gui_defaults section defines class-based defaults that apply to all instances of a given instrument class. This allows you to set common configurations once rather than repeating them for each instrument instance.

Merge Order: __default__ → ClassName → instance-specific

__default__: Settings that apply to ALL instruments unless overridden
Class-specific (e.g., DummyInstrumentWithSubmodule): Settings that apply to all instances of that specific class
Instance-specific: Settings defined in the instrument’s gui.kwargs section

Glob Pattern Matching#

All hide/star/trash lists support glob pattern matching:

Pattern	Description	Example
`*`	Matches any number of characters	`power_*` matches `power_level`, `power_offset`
`?`	Matches exactly one character	`ch?_gain` matches `ch1_gain`, `ch2_gain`
`[seq]`	Matches any character in the sequence	`trace_[0-3]` matches `trace_0` through `trace_3`
`[!seq]`	Matches any character NOT in the sequence	`param_[!xy]` matches `param_a` but not `param_x`

Networking Section#

The networking section configures network addresses for the server:

Field	Description
`listeningAddress`	Additional address to listen for incoming messages
`externalBroadcast`	Address to broadcast parameter changes to (for listeners/dashboards)

Listener Configuration#

The listener configuration file (typically listenerConfig.yml) configures the listener service that subscribes to broadcasts from instrument servers and writes data to storage (InfluxDB or CSV).

Example File#

You can view the example file on GitHub: listenerConfig.yml

# addresses to listen for broadcasts at
addresses: ["tcp://128.174.164.60:6000","tcp://10.192.182.159:6000"]

# list of parameters to listen for, if empty, will listen for all broadcasts
params: ["dummy_instrument_random_number.param0","dummy_instrument_random_number.param2"]

# path to write data to for the CSV listener
csv_path: C:\Users\jmnol\OneDrive\Documents\InstrumentServerData\data.csv

# type of listener (where the listener writes data to)
type: "Influx"

# InfluxDB token for Influx listener
token: "pretty_fridges"

# InfluxDB org for Influx listener
org: "pfafflab"

# InfluxDB buckets for Influx listener, keyed by instrument name
bucketDict: {"fridge_nh": "niflheim","fridge_kk": "kelvin_klein"}

# InfluxDB url for Influx listener
url: "http://localhost:8086"

# measurement Name for Influx listener, keyed by instrument name
measurementNameDict: {"fridge_nh": "niflheim_telemetry", "fridge_kk": "kelvin_klein_telemetry"}

# timezone for Influx listener
timezone_name: "CDT"

Common Fields#

Field	Description
`addresses`	List of addresses to subscribe to broadcasts from (from instrument servers)
`params`	List of parameters to listen for. If empty, listens for all broadcasts
`type`	Type of listener: `"Influx"` or `"CSV"`

InfluxDB-Specific Fields#

Field	Description
`token`	InfluxDB authentication token
`org`	InfluxDB organization name
`bucketDict`	Dictionary mapping instrument names to InfluxDB buckets
`url`	URL where InfluxDB is hosted (e.g., `"http://localhost:8086"`)
`measurementNameDict`	Dictionary mapping instrument names to measurement names
`timezone_name`	Timezone for timestamps (e.g., `"CDT"`, `"UTC"`)

CSV-Specific Fields#

Field	Description
`csv_path`	Path to the CSV file for data output. File will be created if it doesn’t exist

Starting Services#

Starting the Server#

instrumentserver -c serverConfig.yml

To run without the GUI:

instrumentserver -c serverConfig.yml --gui False

Starting the Listener#

instrumentserver-listener -c listenerConfig.yml

To run in the background with output redirected:

nohup instrumentserver-listener -c listenerConfig.yml &

Configuration Files#

Server Configuration#

Example File#

Instruments Section#

GUI Configuration#

GUI Defaults Section#

Glob Pattern Matching#

Networking Section#

Listener Configuration#

Example File#

Common Fields#

InfluxDB-Specific Fields#

CSV-Specific Fields#

Starting Services#

Starting the Server#

Starting the Listener#

This Page