Configuration

Structure

ovos.conf

The ovos_config package determines which config files to load based on ovos.conf. get_ovos_config will return default values that load mycroft.conf unless otherwise configured.

ovos.conf files are loaded in the following order, with later files taking priority over earlier ones in the list:

  • /etc/OpenVoiceOS/ovos.conf
  • /etc/mycroft/ovos.conf (Deprecated)
  • XDG_CONFIG_DIRS + /OpenVoiceOS/ovos.conf
  • /etc/xdg/OpenVoiceOS/ovos.conf
  • XDG_CONFIG_HOME (default ~/.config) + /OpenVoiceOS/ovos.conf

A simple ovos_config should have a structure like:

{
  "base_folder": "mycroft",
  "config_filename": "mycroft.conf",
  "default_config_path": "<Absolute Path to Installed Core>/configuration/mycroft.conf",
  "module_overrides": {},
  "submodule_mappings": {}
}

Note: default_config_path should always be an absolute path. This is generally detected automatically, but any manual override must specify an absolute path to a json or yaml config file.

Non-Mycroft modules may specify alternate config paths. A call to get_ovos_config from neon_core or neon_messagebus will return a configuration like:

{
  "base_folder": "neon",
  "config_filename": "neon.yaml",
  "default_config_path": "/etc/example/config/neon.yaml",
  "module_overrides": {
    "neon_core": {
      "base_folder": "neon",
      "config_filename": "neon.yaml",
      "default_config_path": "/etc/example/config/neon.yaml"
    }
  },
  "submodule_mappings": {
    "neon_messagebus": "neon_core",
    "neon_speech": "neon_core",
    "neon_audio": "neon_core",
    "neon_gui": "neon_core"
  }
}

If get_ovos_config was called from mycroft with the same configuration file as the last example, the returned configuration would be:

{
  "base_folder": "mycroft",
  "config_filename": "mycroft.conf",
  "default_config_path": "<Path to Installed Core>/configuration/mycroft.conf",
  "module_overrides": {
    "neon_core": {
      "base_folder": "neon",
      "config_filename": "neon.yaml",
      "default_config_path": "/etc/example/config/neon.yaml"
    }
  },
  "submodule_mappings": {
    "neon_messagebus": "neon_core",
    "neon_speech": "neon_core",
    "neon_audio": "neon_core",
    "neon_gui": "neon_core"
  }
}

Reading Configuration

ovos_config.config.Configuration is a singleton that loads a single config object. The configuration files loaded are determined by ovos.conf as described above and can be in either json or yaml format.

Using the above example, if Configuration() is called from neon-core, the following configs would be loaded in this order:

  • /etc/example/config/neon.yaml
  • os.environ.get('MYCROFT_SYSTEM_CONFIG') or /etc/neon/neon.yaml
  • os.environ.get('MYCROFT_WEB_CACHE') or XDG_CONFIG_PATH/neon/web_cache.json
  • ~/.neon/neon.yaml (Deprecated)
  • XDG_CONFIG_DIRS + /neon/neon.yaml
  • /etc/xdg/neon/neon.yaml
  • XDG_CONFIG_HOME (default ~/.config) + /neon/neon.yaml

When the configuration loader starts, it looks in these locations in this order, and loads ALL configurations. Keys that exist in multiple configuration files will be overridden by the last file to contain the value. This process results in a minimal amount being written for a specific device and user, without modifying default distribution files.

Configuring Configuration

There are a couple of special configuration keys that change the way the configuration stack loads.

  • Default config refers to the config specified at default_config_path in ovos.conf (#1 /etc/example/config/neon.yaml in the stack above).
  • System config refers to the config at /etc/{base_folder}/{config_filename} (#2 /etc/neon/neon.yaml in the stack above).

protected_keys

A "protected_keys" configuration section may be added to a Default or System Config file (default /etc/mycroft/mycroft.conf). This configuration section specifies other configuration keys that may not be specified in remote or user configurations. Keys may specify nested parameters with . to exclude specific keys within nested dictionaries. An example config could be:

{
  "protected_keys": {
    "remote": [
      "gui_websocket.host",
      "websocket.host"
    ],
    "user": [
      "gui_websocket.host"
    ]
  }
}

This example specifies that config['gui_websocket']['host'] may be specified in user configuration, but not remote. config['websocket']['host'] may not be specified in user or remote config, so it will only consider default and system configurations.

disable_user_config

If this config parameter is set to True in Default or System configuration, no user configurations will be loaded (no XDG configuration paths).

disable_remote_config

If this config parameter is set to True in Default or System configuration, the remote configuration (web_cache.json) will not be loaded.