Configuration

Note

Cockpit uses Microscope to handle the hardware level device communication. This page is concerned with the configuration of Cockpit and assumes you already have working Microscope device servers. For more information on setting up device servers see its documentation.

There are two parts to configuring Cockpit. The configuration of Cockpit proper that covers most of Cockpit options, and the depot configuration which lists all devices that Cockpit will have control over.

Cockpit Configuration

Cockpit configuration controls basic behaviour of Cockpit such as logging level, where to save data as default, and the location of other configuration files. In most cases, the default values will be enough and users will not need to change these.

Config file

Cockpit configuration file spans multiple sections, each section having multiple options (see the Configuration File Format for details). For example:

[global]
data-dir: ~/data
depot-files: /etc/xdg/cockpit/depot/general.conf
             /etc/xdg/cockpit/depot/local.conf
             /etc/xdg/cockpit/depot/experimental.conf

[log]
level: warning
dir: ~/data/logs

The following sections and their options are recognised:

global section

channel-files

List of files defining channel configurations to be loaded by default. Each file can have any number of channels, later files overriding previous channels with the same name. These files can be created via the Channels menu on the menu bar.

config-dir

Directory for the user configuration file, effectively a cache for the last used settings.

data-dir

Directory for the default location to save image data.

depot-files

List of files to use for the device depot. See Depot Configuration.

pyro-pickle-protocol

Pickle protocol version number to use with Pyro, i.e., when connecting to the device server. Defaults to whatever is already set on Pyro which defaults to the highest pickle protocol version available. This affects all Pyro connections.

log section

level

Threshold level for the messages displayed on both the logging window and log files. Only messages that have a severity level equal or higher are displayed. The severity levels are, by increasing order: debug, info, warning, error, and critical.

dir

Directory to create new log files.

stage section

primitives

A list of shapes to draw on stage displays. Primitives are specified by a config entry of the form:

primitives: c 1000 1000 100
             r 1000 1000 100 100

where c x0 y0 radius defines a circle centred on x0, y0 and r x0 y0 width height defines a rectangle centred on x0, y0.

Todo

These options for the stage section are historical and a fudge. They need to be changed and may be removed in the future.

dishAltitude

Dish altitude.

slideAltitude

Slide altitude.

slideTouchdownAltitude

Slide touchdown altitude.

loadPosition

Load position used in the touchscreen.

unloadPosition

Unload position used in the touchscreen.

joystick section

speed

A float scale factor used to mutiply the joystick output to produce stage movement. Smaller numbers make the stage control with joystick slower, while larger numbers make it faster. Default is 0.01

Command line options

Cockpit also takes command line options. Because these take precedence over configuration files, they can be used to override options in the configuration files. The following command line options are available:

--config-file COCKPIT-CONFIG-PATH

File path for another Cockpit config file. This option can be specified multiple times. Options defined in later files override options in previous ones.

--no-config-files

Skip all configuration files other than those defined via command line. It is equivalent to setting both --no-system-config-files and --no-user-config-files options.

--no-system-config-files

Skip all system-wide configuration files, both Cockpit and depot.

--no-user-config-files

Skip the user configuration file, both Cockpit and depot.

--depot-file DEPOT-CONFIG-PATH

Filepath for the depot device configuration. This option can be specified multiple times. If depot files are defined via command line, no other depot files will be read, not even those mentioned on config files.

--debug

Set the logging level to debug.

Precedence of option values

Cockpit can be configured via multiple config files and command line options, so the same option may be defined in multiple places. The precedence order in such case is:

  1. command line option

  2. config file set via command line

  3. user config file

  4. system-wide config files

  5. Cockpit fallback values

This enables users to have a configuration file that overrides system-wide settings, or to use command line options for one-off change of settings.

Depot Configuration

Depot is the collection of devices available to the Cockpit program. Each section of a depot configuration specifies a single device: the section name being the device name, while the options are the device configuration. For example:

[west]
type: cockpit.devices.microscopeCamera.MicroscopeCamera
uri: PYRO:WestCamera@127.0.0.1:8001

[woody]
type: cockpit.devices.executorDevices.ExecutorDevice
uri: PYRO:Sheriff@192.168.0.2:8002

[488nm]
type: cockpit.devices.microscopeDevice.MicroscopeLaser
uri: PYRO:Deepstar488Laser@192.168.0.3:7001
wavelength: 488
triggerSource: woody
triggerLine: 1

defines three devices: a camera named “west”, an executor named “woody”, and a laser light source named “488nm”. Each device has a type option which specifies the fully qualified class name of that device. Each type will require a different set of options which should be documented in its class documentation.

In most cases, each device defined in the depot configuration file corresponds to a Python Microscope device server. Typical exceptions are executor devices which do not exist in Python Microscope, controller devices where each controlled device needs its own section, and objectives.

Multiple depot configurations

Like the Cockpit configuration, depot configuration may span multiple files. Unlike the Cockpit configuration where sections with the same name are merged, each device section must be unique and sections with the same name will cause an error even if in different files.

In the case of depot files, precedence means what files get read. If a set of files is present, the others are not processed. The order is as follow:

  1. depot files in command line options.

  2. depot files in Cockpit config files. If multiple Cockpit config files define depot files, the list of files is read is the one in the file with highest precedence.

  3. depot.conf files in standard, system-dependent locations.

Preferences

In addition to the configuration, Cockpit also keeps a cache of user preferences such as the layout of the different windows, and the last used experiment and device settings. These can be cleared via “Reset User Configuration” on the “Edit” menu.

Location of config files

By default, Cockpit will look for files named cockpit.conf and depot.conf. The location of these files are system-dependent:

OS

System-wide

User

Linux

/etc/xdg/cockpit/

$HOME/.config/cockpit/

MacOS

/Library/Preferences/cockpit/

~/Library/Application Support/cockpit/

Windows

%ProgramData%\cockpit\

%LocalAppData%\cockpit\

Configuration File Format

Configuration files are expected in the INI file format as supported by Python’s configparser. In this format, configuration consists of multiple sections, each named by a [section] header, followed by key/value entries. For example:

[This is the Section Name]
key: value
spaces in keys are allowed: and in keys as well

; A comment line starts with ";" and is ignored.
; It's a good idea to comment configuration files.

[This is the Name of a second Section]
multine values: Just start the following lines
    with white space to create multine values.
    The value can span as many lines as you want.