===================== Robot's Configuration ===================== Global Configuration ==================== In the Aiviro config-file, you can modify different aspects of global robot's behaviour. .. note:: Every configurable value is described as "``value-name`` - data-type [*default value*], value description". And it can be setup using an ``aiviro-cli config set`` command. This will set the values in the backend configuration file. .. code-block:: # Sets API credentials aiviro-cli config login --client-id --api-key # Sets any value in the config file aiviro-cli config set --key cache --key enable --value false # Prints current configuration aiviro-cli config print Global configuration is loaded automatically from 3 different locations, and in the following order is merged together (e.g. user-configuration overwrites any setting from the backend-configuration): 1. **Default configuration**, which is stored in the package. 2. **Backend configuration**, which can be edited by setting ``AIVIRO__BACKEND_CONFIG_PATH`` environment variable or by default is loaded from configuration directory: * MacOS - `~/Library/Application Support/aiviro/config.yml` * Linux - `~/.config/aiviro/config.yml` * Windows - `AppData/aiviro/config.yml` 3. **User configuration**, which can be edited by setting ``AIVIRO__USER_CONFIG_PATH`` environment variable or by default is loaded from the current working directory, e.g. `./config.yml`. Credentials ----------- Aiviro needs to have access to our servers to recognize texts and elements on the screen. For accessing our servers, you need to have a valid ``client_id`` and ``api_key``. .. code-block:: yaml credentials: client_id: "your-client-id" api_key: "super-secret-api-key" Vision Server ------------- This configuration defines a communication protocol and address to our servers for OCR and Elements detection. .. warning:: Configuration options were changed in version 3.7.0, old configuration was removed. .. code-block:: yaml vision-server: protocol: https api_url: api.aiviro.com ocr_model: stable ouir_model: stable max_cache: 2 * ``protocol`` - protocol for detection endpoint, where ocr and elements as buttons, inputs, etc. are recognized. * ``api_url`` - endpoint of detection server. * ``ocr_model`` - str [*stable*], type of the model to use for ocr recognition (*stable* & *develop* available). * ``ouir_model`` - str [*stable*], type of the model to use for elements recognition (*stable* & *develop* available). * ``max_cache`` - int [*5*], number of last predictions to store in local cache for faster image recognition Cache ----- When Aiviro has to find an element on the screen, a screen of the display is sent to our servers for OCR and element recognition which can take up to half of a second of processing time. For example if we want to click the button 'Log in' (``robot.click(Button('Log In'))``), Aiviro sends the screen to our servers and from the results finds the correct element and clicks it. By enabling cache, every element which was found is stored locally on the machine running Aiviro. If the same element ``Button('Log In')`` needs to be found again, Aiviro will use the element from a cache instead of sending the screen for image recognition. Using cache will result in faster processing for future runs. .. code-block:: yaml cache: enable: true folder: logs/ * ``enable`` - boolean [*true*], Defines if cache is enabled or not. * ``folder`` - str [*logs/*], Path to a folder where cache related files will be stored, relative or absolute path is supported. Logging ------- Aiviro is from every run of your script collecting locally logs. These logs can be used for checking what Aiviro sees but also in case of problem, we can see what went wrong. Logs can be split into two types: * **text logs** - contain information, e.g. which texts were compared during a search for the element or which commands were called, * **image logs** - contain screenshots which Aiviro used with a corresponding elements' bound-boxes, further about this in :ref:`Generate Images` section. .. code-block:: yaml logger: timezone: Europe/Berlin logging_levels: aiviro: DEBUG log_folder: logs/ log_to_file: true log_images: true log_compression: false max_disk_size: "0B" max_number_of_logs: 0 upload-server: protocol: http api_url: 10.128.32.5:6400 generate_images: enable: true last_n_images: 0 buffer: image_enable: false image_limit: 20 text_enable: false text_limit: 200 .. _pytz: https://pypi.org/project/pytz/ * ``timezone`` - str [*Europe/Berlin*], used to generate correct time in logs, the value can be any timezone supported by the pytz_ library. * ``logging_levels`` - list of loggers with their logging levels. All loggers inherit from main *aiviro* logger. * ``log_folder`` - str [*logs/*], Path to a folder where all logs will be stored, relative or absolute path is supported. * ``log_to_file`` - boolean [*true*], Defines if Aiviro will store *text logs*. * ``log_images`` - boolean [*true*], Defines if Aiviro will store *image logs*. This setting do not interfere with :ref:`Image Buffer`. * ``log_compression`` - boolean [*false*], Defines if all logs will be compressed into one *.zip* file. * ``max_disk_size`` - int/string [*0*], Number of bytes or string with number and SI-prefix. Defines maximum disk size of the logging folder. This value is not a hard cap for the disk size, robot logs can exceed this size, but on the next run everything exceeding this value is deleted. If set to *0* max-disk-size check is skipped. * ``max_number_of_logs`` - int [*0*], Maximum number of logs kept in log folder. If set to *0* max-number-of-logs check is skipped. Image Buffer ~~~~~~~~~~~~ .. warning:: Configuration options ``image_buffer_enable`` & ``image_buffer_limit`` were removed in version 3.13.0, use new configuration ``buffer`` instead. Buffer is keeping last-n debug images and text logs, specified by ``*_limit``, in a memory. Data from the image buffer are used by :meth:`~.BaseRobot.emit_image_logger_buffer` or for generating GIF :meth:`~.BaseRobot.create_gif_from_buffer`. * ``image_enable`` - boolean [*true*], Defines if image-buffer is enabled or disabled. * ``image_limit`` - int [*20*], Limit the maximal number of images that can be stored inside the buffer. * ``text_enable`` - boolean [*true*], Defines if text-buffer is enabled or disabled. * ``text_limit`` - int [*200*], Limit the maximal number of text logs that can be stored inside the buffer. * ``upload-server`` - *protocol* and *api_url* for Aiviro-Dashboard server, where logs from the buffer can be uploaded. .. note:: | See :meth:`~.BaseRobot.emit_image_logger_buffer` for further information about how *image-buffer* can save and upload the logs. | See :meth:`~.BaseRobot.create_gif_from_buffer` for information about generating GIF from *image-buffer*. Generate Images ~~~~~~~~~~~~~~~ When Aiviro is saving *image logs*, it always stores two files, raw image of the screen and json file with corresponding metadata for that screen. These logs are not easily human-readable, therefore you can enable automatic or also manual generating of images, which combine these metadata and raw images together for better human-readable output. * ``enable`` - boolean [*true*], Defines if automatic generating of images is enabled or disabled. * ``last_n_images`` - int [*0*], Total number of last N images to generate. If set to 0, it will generate all images. .. warning:: | In longer aiviro-scripts it can take significant time to generate image-logs! | We recommend to set-up ``last_n_images`` option in the config-file. Generating image-logs can be done also manually, after running aiviro-scripts, by using *aiviro-cli*. For further information see :ref:`Process Metadata Logs` section. Video-streaming --------------- Every type of robot is able to video-stream what it sees, this is especially useful while using a headless :class:`~.WebRobot` or :class:`~.RDPRobot`. .. code-block:: yaml streaming: enable: true ip_address: localhost port: 12345 print_port: 6262 access_token: super-secret-token pause_until_client: false pause_timeout: 120 * ``enable`` - boolean [*true*], Defines if streaming is enabled or disabled. * ``ip_address`` - str [*localhost*], IP address for streaming URL. * ``port`` - optional[int], If not set, random and empty port will be used for streaming. * ``print_port`` - optional[int], If set, this port will be printed into stdout for streaming URL. * ``access_token`` - optional[str], Required parameter in streaming URL to access it, if not set, automatically generated token is used. * ``pause_until_client`` - boolean [*false*], Pauses execution of the script until client is connected to streaming socket. * ``pause_timeout`` - int [*60*], Timeout for script execution until client is connected to streaming socket. .. note:: The video stream can be open in any browser and the URL is printed into stdout at the start of the script. Be aware that *port* and *access_token* are always selected randomly, every run of the script has a different URL. For testing purposes, this can be overridden in the configuration file, as shown above. Here is an example of streaming URL based on the configuration above: ``http://localhost:6262/?access_token=super-secret-token``. Here is without specifying the ``print_port``: ``http://localhost:12345/?access_token=super-secret-token``. Webdriver --------- Webdriver is a required when using :class:`~.WebRobot`. .. code-block:: yaml webdriver: linux: /usr/bin/chromedriver windows: path/to/chromedriver.exe * ``webdriver`` - *key* is a platform name and *value* is path to a webdriver executable file. User Configuration ================== .. automodule:: aiviro.core.utils.configuration.user_config :members: UserConfig