.. _quickstart: Quick start guide ----------------- First time set-up ````````````````` .. note:: This section assumes that **tomato** has been successfully :ref:`installed`. To prepare **tomato** for its first execution, you need to supply additional information configuring the package. The easiest way to do this is to execute **tomato** in verbose mode: .. code-block:: :linenos: :emphasize-lines: 3 PS C:\Users\krpe> tomato -vv DEBUG:tomato.main:loglevel set to 'DEBUG' DEBUG:tomato.setlib.functions:local config folder is 'C:\Users\krpe\AppData\Local\dgbowl\tomato\0.2a1' DEBUG:tomato.setlib.functions:local data folder is 'C:\Users\krpe\AppData\Local\dgbowl\tomato\0.2a1' DEBUG:tomato.setlib.functions:local log folder is 'C:\Users\krpe\AppData\Local\dgbowl\tomato\0.2a1\Logs' WARNING:tomato.setlib.functions:config file not present. Writing defaults to 'C:\Users\krpe\AppData\Local\dgbowl\tomato\0.2a1\settings.toml' ... As you see on ``line 3`` in this verbose output, **tomato** is configured to store its local configuration data in a user-accessible folder: - ``$env:localappdata\dgbowl\tomato\`` on Windows, - ``$HOME/.config/`` on Linux. Within this ``local config folder``, **tomato** expects to find at least the :ref:`setfile` (``settings.toml``). As you can also see from the log, on Windows the ``local data folder`` is by default also set to the same path, therefore all of **tomato's** information (*device* settings, *state* and *queue* tables, *job* data) will be located in this versioned folder. .. _setfile: Settings file ````````````` The settings file named ``settings.toml`` has to be located in the ``local config folder``. The default file generated by the first run of ``tomato -vv`` above looks similar to the below file: .. code-block:: toml :linenos: [state] type = 'sqlite3' path = 'C:\Users\krpe\AppData\Local\dgbowl\tomato\0.1rc11\database.db' [queue] type = 'sqlite3' path = 'C:\Users\krpe\AppData\Local\dgbowl\tomato\0.1rc11\database.db' storage = 'C:\Users\krpe\AppData\Local\dgbowl\tomato\0.1rc11\Jobs' [devices] path = 'C:\Users\krpe\AppData\Local\dgbowl\tomato\0.1rc11\devices.yml' [drivers] [drivers.biologic] dllpath = 'C:\EC-Lab Development Package\EC-Lab Development Package' The sections ``[state]`` and ``[queue]`` contain the ``path`` of the database containing the *state* and *queue* tables, as well as the database ``type``. For ``queue``, the ``storage`` entry points to the folder where the raw data generated by *jobs* will be stored. .. note:: As of ``tomato-0.2a1``, only ``sqlite3`` is supported as a database ``type``. The ``[devices]`` section within the ``settings.toml`` file points to a ``yaml``-formatted :ref:`devfile`, defining the hardware configuration of the devices managed by **tomato**. Additional, *driver*-specific settings (such as the ``dllpath`` required by the :mod:`~tomato.drivers.biologic` driver) may be provided in the ``[drivers]`` section. .. _devfile: Devices file ```````````` This ``yaml``-formatted file contains information about each *device*, corresponding to an individual piece of hardware managed by **tomato**, as well as information about the organisation of such *devices* into addressable chunks, called *pipelines*. The *pipelines* can be thought of as digital twins of experimental set-ups, and should contain all *devices* required to carry out a *payload* (see :ref:`payfile`). **devices** section ******************* .. code-block:: yaml :linenos: devices: - name: MPG2-8 address: "192.109.209.8" channels: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16] driver: "biologic" pollrate: 60 capabilities: - open_circuit_voltage - constant_current - constant_voltage - sweep_current - sweep_voltage - loop In the example ``devices`` section above, we define a single BioLogic MPG2 potentiostat. Each entry in this section has to define the ``name`` of the instrument, the ``address`` and ``channels`` available and used for connecting to the instrument, the ``driver`` with which **tomato** will manage this *device*, the ``pollrate`` specifying the polling frequency with which the **tomato** daemon queries the worker job for data, and finally a list of the ``capabilities`` this *device* supports. .. note:: The ``pollrate`` here is an internal setting for **tomato** and defaults to 10 s. It is the frequency with which the *job* daemon supervising the *device* asks the *driver* for new data, **not** the frequency with which the *driver* asks the hardware for data! **pipelines** section ********************* .. code-block:: yaml :linenos: :emphasize-lines: 2-6 pipelines: - name: MPG2-7-10 devices: - tag: MPG2 name: MPG2-7 channel: 10 - name: MPG2-8-* devices: - tag: MPG2 name: MPG2-8 channel: each In the example ``pipelines`` section above, we show two ways of defining *pipelines* in **tomato**. In the first entry on ``lines 2-6``, we define a *pipeline* by its ``name``, and assign a list of *devices* into it, identified within the *pipeline* by their ``tag``, and matched against the ``devices`` section using the ``name`` and ``channel``. Alternatively, for multi-channel *devices*, such as the ``MPG2-8`` defined in the example above, a shorthand for defining a *pipeline* for each ``channel`` is shown in the second entry. The pipeline ``name`` will be generated by replacing the ``*`` with each ``channel``. Multiple *devices* can be combined into a single *pipeline* using the above syntax. .. _payfile: Payload file ```````````` The *payload* file contains all information required to enter a *job* into the *queue*. The overall schema of the *payload* is defined in the :mod:`dgbowl_schemas.tomato` module, and is parsed using :func:`dgbowl_schemas.tomato.to_payload`: .. autopydantic_model:: dgbowl_schemas.tomato.payload_0_2.Payload