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 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.
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:
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.
Directory for the user configuration file, effectively a cache for the last used settings.
Directory for the default location to save image data.
List of files to use for the device depot. See Depot Configuration.
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.
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.
Directory to create new log files.
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
c x0 y0 radiusdefines a circle centred on
r x0 y0 width heightdefines a rectangle centred on
These options for the stage section are historical and a fudge. They need to be changed and may be removed in the future.
Slide touchdown altitude.
Load position used in the touchscreen.
Unload position used in the touchscreen.
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:
File path for another cockpit config file. This option can be specified multiple times. Options defined in later files override options in previous ones.
Skip all configuration files other than those defined via command line. It is equivalent to setting both
Skip all system-wide configuration files, both cockpit and depot.
Skip the user configuration file, both cockpit and depot.
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.
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:
command line option
config file set via command line
user config file
system-wide config files
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 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:
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
depot.conf. The location of these files are system-dependent:
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.