Managing setups

A setup, internally known as a host, is an object which defines a physical setup.

Adding a setup

Setups can be added by clicking New setup on the launch window.

Every setup depends on a Python binary, which can be the system's installation or an embedded binary. All Python packages present in this installation's import path will be searched for plugins.

Installing plugins

Plugins are installed by updating the requirements.in file in the setup's directory. The setup's directory can be found from the launch window: Right click on a setup → Reveal settings in explorer → Open requirements.in.

The requirements.in file can be opened with a text editor. Each line in this file maps to a Python package which can provide zero or more plugins, although usually a single plugin.

To add a package, add a line with the corresponding package's name, as visible on PyPI or the official Automancer package registry. You can optionally add a version number, for example pr1-nikon-microscope~=4.2.0 to enforce version 4.2.x.

  --extra-index-url (...)

  pip-tools~=6.13.0

  pr1
  pr1-server

  # Add packages below

  pr1-amf
  pr1-core
+ pr1-nikon-microscope

Packages mentioned in this file will be installed when launching the setup, which can take a few minutes. Plugins contained in the package will be automatically loaded and enabled shortly after.

To remove a package, remove the corresponding line and restart the setup. To update a package, optionally update the provided version number and restart the setup. To install plugins for development, see Plugin development.

Configuring a setup

A setup's configuration can be found from the launch window: Right click on a setup → Reveal settings in explorer → Open setup.yml. This file is written in PCRL. For more information, see Writing PCRL.

The following root attributes are available:

• id (identifier, required) – A unique id associated to this setup. Automatically generated.
• name (string, required) – The name of the setup. Automatically generated with the computer's name.
• plugins (map, required) – A dictionary listing the configuration of every plugin.
• version (string, required) – The version of the configuration's schema, for backwards compatibility. Automatically generated and updated.

Plugins

The configuration of plugins is provided in the setup configuration file as key-value pairs where the key is the plugin's namespace.

units:
  nikon_microscope:
    # <- Options regarding plugin initialization here
    options:
      # <- Options passed to the plugin here

The following options for plugin initialization are available:

• development (boolean) – Whether to load the plugin in development mode. Defaults to false.
• enabled (boolean) – Whether the plugin is enabled. Defaults to true.
• options (object) – Options passed to the plugin. Defaults to an empty dictionary.

By default, all plugins installed in sys.path are loaded and enabled even if they are not mentioned in the configuration.

Registering devices

Several plugins interact with external devices and follow a similar pattern when defining the configuration of these devices. This configuration starts with a devices attribute in the plugin options, which defines a list of devices. Each device can the following properties:

• id (identifier, required) – A string unique to this device among all devices in the setup. This id will be used to reference the device in protocols.
• label (string) – The name of the device. Defaults to a name provided by the device itself, the name of its manufacturer, the device's model, its serial number, its id, or a similar string.
• model (string, sometimes required) – The model of the device. This can sometimes be detected automatically by communicating with the device or using information from the underlying protocol, such as the product id in the case of USB.
• One or more options to locate the device, such as:
  • address (number or string) – The address of the device, such as an IP address and port (e.g. 17.244.221.152:6513), a full address with credentials (e.g. user:pass@server.net), a serial port (e.g. COM3 or /dev/tty.usbmodem1101) or a USB bus address (e.g. 5).
  • serial (string) – The serial number of the device, as defined by the manufacturer.
• Other options depending on the plugin and model.

Below is an example:

units:
  nikon_microscope:
    options:
      devices:
        - id: Microscope1
          label: Microscope no. 1
          model: NikonTi1
          address: COM3
          # <- Other options here
        - id: Microscope2
          # ...

Troubleshooting launch errors

All errors that occur during launch are printed to a log file, which can be found from the launch window: Right click on a setup → Reveal logs in explorer. The file with the largest number corresponds to the latest log.