Handling of devices
===================

The ``xrdt device`` CLI allows to manage devices relevant for XRD measurements.
Once a device is registered, it can be assigned to a preset or measurement.

The CLI tool provides commands to ``list``, ``add``, and ``remove`` device(s), which are briefly described underneath.
Moreover, the ``xrdt device edit`` command allows to open the ``JSON`` device file with an external editor.
A full documentation of all commands and their options is provided in the section :ref:`cli`.

.. code-block:: text

   Usage: xrdt device [OPTIONS] COMMAND [ARGS]...

     CLI to manage measurement devices.

   Options:
     --devices PATH  Path to the device file (JSON).  [default:
                     ~/.local/xrdt/devices.json; required]
     --help          Show this message and exit.

   Commands:
     add     Create and register a new device.
     edit    Open the device file with an editor.
     list    List all registered devices.
     remove  Remove a registered device.


Add a new device
----------------

A new device can be added via the ``xrdt device add`` command.
Optionally, a device ``--name <NAME>`` and a ``--device-type <TYPE>`` can be specified to the command.
The type has to correspond the one of the options listed in the usage information (``run xrdt device add --help``).
Currently the types ``"X-ray diffractometer"`` and ``"High-temperature chamber"`` are available.
If no arguments are specified, the script will prompt for input and will ensure that valid parameter are accepted.

If you execute the command as shown underneath, you will be prompted to provide certain input values.

.. code-block:: bash

  xrdt device add

The example for the addition of a device is shown underneath.

.. code-block:: text

  Enter a name for the new device: test_diffractometer
   > Define manufacturer: Evil company
   > Define model: Irradiator 2000
   > Define inventory_no: 13
  Added device: 'test_diffractometer' (X-ray diffractometer)

After entering the name for the new device, a selection menu allows you to define its type.
Based on the device type, certain input values have to be defined.
In the example above, a device of type ``"X-ray diffractometer"`` is added, as shown in the last line of the output.


List registered devices
-----------------------

The command ``xrdt device list`` allows to obtain a list of all registered devices.
The list contains the type of device and the device name.
After the addition of the device in the previous example, its output looks as follows:

.. code-block:: text

  Registered devices:
   * X-ray diffractometer: test_diffractometer


Remove a registered device
--------------------------

A device can be removed via the ``xrdt device remove`` command.
Optionally, a device ``--name <NAME>`` and a ``--force`` flag can be specified to the command.
The latter allows to skip a confirmation prompt.
If no device name is provided, the script will offer a selection dialogue to choose one.

.. code-block:: text

  Are you sure you want to remove 'test_diffractometer' [y/N]? y
  Removed device: 'test_diffractometer' (X-ray diffractometer)