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 in your terminal. This will set the values in the Backend configuration file.

# Sets API credentials
$ aiviro-cli config login --client-id <client-id> --api-key <api-key>

# Sets any value in the config file, e.g. setting value "{"cache": "enable": false}"
$ 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 Aiviro python package.

  2. Backend configuration, which can be edited by setting AIVIRO__BACKEND_CONFIG_PATH environment variable or by default is loaded from the following 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.

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.

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.

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 collects local logs during every run of your script. These logs serve a dual purpose – they provide insight into what Aiviro observes and, in the event of an issue, enable us to pinpoint 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 Generate Images section.

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

  • 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 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 emit_image_logger_buffer() or for generating GIF 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 emit_image_logger_buffer() for further information about how image-buffer can save and upload the logs.
See 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 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 WebRobot or RDPRobot.

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 WebRobot.

Warning

Configuration options webdriver were deprecated in version 3.20.0, add the path to the webdriver executable file in the PATH environment variable.

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

class aiviro.core.utils.configuration.user_config.UserConfig

It creates a way for user to change various configuration options of the Robot. It can be accessed as aiviro.user_config.

property text_similarity_threshold: float | None

Custom text similarity threshold value.

Getter:

Returns value of the threshold

Setter:

Sets value of the threshold, it must be float number between 0 and 1, or None to use default value

Example:

>>> import aiviro
>>> r = aiviro.create_desktop_robot()
>>> aiviro.user_config.text_similarity_threshold = 0.8
>>> r.see(aiviro.Text("X12GP-WR34", aiviro.text_find_methods.SIMILAR))
>>> aiviro.user_config.text_similarity_threshold = None
property text_normalization: Callable[[str], str] | None

Custom normalization method to change the detected OCR text in any way.

Getter:

Returns normalization method

Setter:

Sets normalization method, it must be a callable object with one input argument (str) and returns (str)

Example:

>>> import aiviro
>>> aiviro.user_config.text_normalization = lambda x: x.replace("O", "0")
>>> r = aiviro.create_desktop_robot()
>>> r.see(
...     aiviro.Text(
...         r"\d+",
...         aiviro.find_method.REGEX.USER_NORMALIZATION,
...     )
... )
property implicit_wait: int

Number of seconds to wait for every search-object to appear on the screen. Functionality of implicit wait is similar as calling wait_for() command. But implicit wait works for every command that needs to process some search-object.

Warning

This parameter does not apply for get(), wait_for() & wait_until_disappear() commands.

Getter:

Returns value of implicit wait

Setter:

Sets timeout of implicit wait, it must be <int> number. To disable implicit wait set it to None or 0.

Example:

>>> import aiviro
>>> aiviro.user_config.implicit_wait = 5
>>> r = aiviro.create_desktop_robot()
>>> r.type_text(aiviro.Input("Password"), "*******", sensitive_data=True)
>>> r.click(aiviro.Button("Submit"))

>>> # the example above could be rewritten without implicit-wait
>>> import aiviro
>>> r = aiviro.create_desktop_robot()
>>> input_box = r.wait_for(aiviro.Input("Password"), timeout=5)
>>> r.type_text(input_box, "*******", sensitive_data=True)
>>> r.click(aiviro.Button("Submit"))
property text_find_strategy: List[FindMethod]

List of find methods that are used to find elements with text on the screen. Enables to set several find methods to try in case the previous did not find the element.

Getter:

Returns list of find methods

Setter:

Sets list of find methods, it must be a list of FindMethod

Example:

>>> import aiviro
>>> aiviro.user_config.text_find_strategy = [
...     aiviro.find_method.SIMILAR,
...     aiviro.find_method.EQUAL,
... ]
>>> r = aiviro.create_desktop_robot()
>>> r.see(aiviro.Text("X12GP-WR34", find_method=aiviro.find_method.AUTO)