Configuration API¶

Module: typhoon.api.configuration

Configuration API is a set of methods used to read and update the predefined configuration of Typhoon HIL Control Center.

API references ¶

class ConfigurationAPI(*args, **kwargs)¶

Gets the current value of a configuration item specified by key.

Parameters:: key (str) – The identifier for the configuration item to retrieve. It can also be partial (e.g., “general” or “general.autosave”) to get a part of the configuration, or empty to get the whole configuration.
Returns:: The current value of the configuration item. The type can be str, float, int, bool, dict, list or None.
Return type:: JSONSchemaValue
Raises:: KeyError – If the key is not part of the configuration schema.

Note

Only predefined keys are available for use. For a complete list of configuration keys and their descriptions check out the “get_schema” method example below.

Example:

#
# Get a typed value from the configuration by key
#
from typhoon.api.configuration import configuration

autosave_interval: int = configuration.get("general.autosave.interval")
print(f"The autosave interval is {autosave_interval} seconds.")

# Get values prefixed with partial key
general_configuration = configuration.get("general")
print(general_configuration)

Output

The autosave interval is 180 seconds.
{'general.autosave.interval': 180, 'general.autosave.file_extension': '.bak'}

get_schema(key: str = '') → JSONSchema¶

Retrieves the schema for a configuration item identified by the key.

Parameters:: key (str, optional) – The identifier for the configuration item to retrieve. It can also be partial (e.g., “general” or “general.autosave”) to get a part of the schema, or empty to get the whole schema.
Returns:: The schema for the configuration item in JSONSchema format.
Return type:: JSONSchema
Raises:: KeyError – If the key is not part of the configuration schema.

Note

Schema keys marked with “internal” are not visible in the settings UI located in the Typhoon HIL Control Center, but are still available for use in the API.

Example:

#
# Get the schema of all the configuration keys
#
import json
from typhoon.api.configuration import configuration

schema = configuration.get_schema()
print(json.dumps(schema, indent=4))

Output

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "/typhoon/thcc/configuration/schema.json",
    "title": "Typhoon HIL Control Center Configuration Schema",
    "description": "JSON Schema describing the configuration of various parts of the Typhoon HIL Control Center",
    "type": "object",
    "properties": {
        "general.autosave.interval": {
            "type": "number",
            "markdownDescription": "\n            Interval (in seconds) between auto-saves in the HIL SCADA and Schematic Editor.\n            ",
            "default": 180,
            "minimum": 3,
            "maximum": 36000
        },
        "general.autosave.file_extension": {
            "type": "string",
            "markdownDescription": "\n            File extension for autosave files. The default extension is '.bak'.\n            ",
            "default": ".bak",
            "pattern": "^\\.[a-zA-Z0-9]{1,10}$",
            "patternErrorMessage": "Extension must start with a period and contain 1-10 alphanumeric characters. E.g., '.bak'"
        },
        "debug.logging_on": {
            "type": "boolean",
            "markdownDescription": "\n                Enables or disables logging.\n                The file <code>server.log</code> is created in the source directory.\n                This settings is disabled by default.\n            ",
            "default": false,
            "internal": true
        },
        "paths.user_lib_dir": {
            "title": "User Library Directories",
            "type": "object",
            "description": "User library directories to include. Each item represents a directory, and if its checkbox is checked the subdirectories will be included in the path as well.",
            "additionalProperties": {
                "type": "boolean",
                "description": "Indicates whether the library path should be imported recursively."
            },
            "default": {},
            "examples": [
                {
                    "C:\\Users\\DefaultUser\\AppData\\Roaming\\typhoon\\user-libs": true
                }
            ],
            "internal": true
        },
        "external_tools.psim_path": {
            "title": "PSIM Installation Directory",
            "type": "string",
            "markdownDescription": "\n                Specifies the installation directory of the PSIM tool, if used. Empty if not set.\n                <br><br>\n                <b>Note:</b>\n                <br>\n                In order to import PSIM schematic files, the PSIM software v12.0.3 or later has to\n                be installed and activated with a valid license on your PC. <br>\n                If you still do not have the PSIM software,\n                please contact: <a href='https://powersimtech.com/products/psim/'>https://powersimtech.com/products/psim/</a>\n            ",
            "default": ""
        },
        "control_center.hil_setup.default_path": {
            "type": [
                "string",
                "null"
            ],
            "description": "Default path for HIL setup files. Typhoon HIL Control Center needs to be restarted for changes to take effect.",
            "default": null,
            "internal": true
        },
        "control_center.hil_setup.custom_ip_addresses": {
            "type": "array",
            "description": "Specify a list of IP addresses where HIL devices are located if auto discovery fails to find them. Typhoon HIL Control Center needs to be restarted for changes to take effect.",
            "items": {
                "type": "string",
                "format": "ipv4"
            },
            "default": [],
            "internal": true
        },
        "hil_activation.proxy.address": {
            "type": "string",
            "description": "HIL Activation Proxy Address. ",
            "default": "",
            "internal": true
        },
        "hil_activation.proxy.port": {
            "type": "integer",
            "description": "HIL Activation Proxy Port. ",
            "default": 80,
            "minimum": 1,
            "maximum": 65535,
            "internal": true
        },
        "hil_activation.proxy.username": {
            "type": "string",
            "description": "HIL Activation Proxy Username. ",
            "default": "",
            "internal": true
        },
        "hil_activation.proxy.password": {
            "type": "string",
            "description": "HIL Activation Proxy Password. ",
            "default": "",
            "internal": true
        },
        "hil_activation.proxy.authentication_method": {
            "type": "string",
            "markdownDescription": "\n            HIL Activation Proxy Authentication Method.\n            HIL Activation Proxy Authentication Method.\n            The default authentication method is <code>BASIC_AUTHENTICATION</code>.\n            ",
            "default": "BASIC_AUTHENTICATION",
            "enum": [
                "BASIC_AUTHENTICATION",
                "DIGEST_AUTHENTICATION"
            ],
            "enumDescriptions": [
                "The username and password are sent in clear text.",
                "The username and password are hashed before sending."
            ],
            "internal": true
        },
        "hil.server_rep_port": {
            "title": "HIL Server Response Port",
            "type": [
                "integer",
                "null"
            ],
            "description": "HIL Server's response port. This parameter is assigned a random port between 49152 and 65535 at startup.",
            "default": null,
            "minimum": 1,
            "maximum": 65535,
            "internal": true
        },
        "signal_analyzer.recent_files.recent_data_files": {
            "type": "array",
            "description": "List of recently opened signal analyzer data files.",
            "items": {
                "type": "string"
            },
            "default": [],
            "internal": true
        },
        "schematic_editor.perspective": {
            "type": "string",
            "enum": [
                "REAL_TIME",
                "TYPHOONSIM",
                "BOTH"
            ],
            "enumDescriptions": [
                "Real-time perspective",
                "TyphoonSim perspective",
                "Integrated perspective"
            ],
            "default": "BOTH",
            "description": "Schematic editor perspective.",
            "internal": true
        },
        "schematic_editor.recent_files.recent_schematic_files": {
            "type": "array",
            "description": "List of recently opened schematic (.tse) files.",
            "items": {
                "type": "string"
            },
            "default": [],
            "internal": true
        },
        "schematic_editor.server_rep_port": {
            "title": "Schematic Editor Server Response Port",
            "type": [
                "integer",
                "null"
            ],
            "description": "Schematic Editor Server's response port. This parameter is assigned a random port between 49152 and 65535 at startup.",
            "default": null,
            "minimum": 1,
            "maximum": 65535,
            "internal": true
        },
        "scada.recent_files.recent_model_files": {
            "type": "array",
            "description": "List of recently opened model files.",
            "items": {
                "type": "string"
            },
            "default": [],
            "internal": true
        },
        "scada.recent_files.recent_model_settings_files": {
            "type": "array",
            "description": "List of recently opened model settings files.",
            "items": {
                "type": "string"
            },
            "default": [],
            "internal": true
        },
        "scada.recent_files.recent_hil_scada_files": {
            "type": "array",
            "description": "List of recently opened HIL SCADA files.",
            "items": {
                "type": "string"
            },
            "default": [],
            "internal": true
        },
        "scada.recent_directories.last_cpd_files_dir": {
            "title": "Last CPD Files Directory",
            "type": [
                "string",
                "null"
            ],
            "description": "Last used directory for CPD files.",
            "default": null,
            "internal": true
        },
        "typhoon_test_ide.recent_files.recent_scripts": {
            "type": "array",
            "description": "List of recently opened scripts.",
            "items": {
                "type": "string"
            },
            "default": [],
            "internal": true
        },
        "typhoon_test_ide.interpreters.custom_interpreter_cmd": {
            "type": [
                "string",
                "null"
            ],
            "title": "Custom Interpreter Command",
            "description": "Custom interpreter command.",
            "default": null,
            "internal": true
        },
        "typhoon_test_ide.pdf.trace": {
            "type": "boolean",
            "description": "Enable or disable trace in the PDF report.",
            "default": false,
            "internal": true
        },
        "typhoon_test_ide.pdf.plots": {
            "type": "boolean",
            "description": "Enable or disable plots in the PDF report.",
            "default": true,
            "internal": true
        },
        "typhoon_test_ide.pdf.steps": {
            "type": "boolean",
            "description": "Enable or disable steps in the PDF report.",
            "default": true,
            "internal": true
        },
        "typhoon_test_ide.pdf.slogan": {
            "type": "string",
            "description": "Slogan to be displayed in the PDF report.",
            "default": "**Test**\n**_Design_**\n_Deploy_",
            "internal": true
        },
        "typhoon_test_ide.pdf.color": {
            "type": "string",
            "description": "Color for the PDF report heading text in HEX format (eg. #333333).",
            "default": "#333333",
            "pattern": "^#[0-9a-fA-F]{6}$",
            "internal": true
        },
        "typhoon_test_ide.pdf.title": {
            "type": "string",
            "description": "Title for the PDF report.",
            "default": "Typhoon HIL Test session report",
            "internal": true
        },
        "typhoon_test_ide.pdf.work_dir": {
            "type": "boolean",
            "markdownDescription": "\n            Use the working directory for the PDF report.\n            If disabled, the file path configured in <a href=\"typhoon_test_ide.pdf.file_path\">PDF: File Path</a> will be used.\n            ",
            "default": true,
            "internal": true
        },
        "typhoon_test_ide.pdf.file_path": {
            "type": "string",
            "markdownDescription": "\n            File path for the PDF report.\n            This path is ignored if <a href=\"typhoon_test_ide.pdf.work_dir\">PDF: Work Dir</a> is enabled.\n            ",
            "default": "",
            "internal": true
        },
        "typhoon_test_ide.pdf.typhoon_logo": {
            "type": "boolean",
            "description": "Include the Typhoon HIL logo in the PDF report.",
            "default": true,
            "internal": true
        },
        "typhoon_test_ide.pdf.logo": {
            "type": "string",
            "markdownDescription": "\n            Path to a custom logo to include in the PDF report.\n            This path is ignored if <a href='typhoon_test_ide.pdf.typhoon_logo'>PDF: Typhoon Logo</a> is enabled.\n            ",
            "default": "",
            "internal": true
        },
        "scada.server_rep_port": {
            "title": "SCADA Server Response Port",
            "type": [
                "integer",
                "null"
            ],
            "description": "SCADA Server's response port. This parameter is assigned a random port between 49152 and 65535 at startup.",
            "default": null,
            "minimum": 1,
            "maximum": 65535,
            "internal": true
        },
        "pv_generator.server_rep_port": {
            "title": "PV Generator Server Response Port",
            "type": [
                "integer",
                "null"
            ],
            "description": "PV Generator Server's response port. This parameter is assigned a random port between 49152 and 65535 at startup.",
            "default": null,
            "minimum": 1,
            "maximum": 65535,
            "internal": true
        },
        "firmware_manager.server_rep_port": {
            "title": "Firmware Manager Server Response Port",
            "type": [
                "integer",
                "null"
            ],
            "description": "Firmware Manager Server's response port. This parameter is assigned a random port between 49152 and 65535 at startup.",
            "default": null,
            "minimum": 1,
            "maximum": 65535,
            "internal": true
        },
        "vhil.announcement_port_range": {
            "type": "string",
            "description": "Range of ports for announcements. The format is a dash-delimited range, e.g., '40000-40050'.",
            "pattern": "^[0-9]{1,5}-[0-9]{1,5}$",
            "default": "40000-40050",
            "internal": true
        },
        "communication.announcement_port_req_range": {
            "title": "Announcement Port Request Range",
            "type": "string",
            "description": "Range for announcement port requests. The format is a dash-delimited range, e.g., '30000-30100'.",
            "default": "30000-30100",
            "pattern": "^[0-9]{1,5}-[0-9]{1,5}$",
            "examples": [
                "30000-30100"
            ],
            "internal": true
        },
        "communication.announcement_port_pub_range": {
            "title": "Announcement Port Publication Range",
            "type": "string",
            "description": "Range for announcement port publications. The format is a dash-delimited range, e.g., '50000-50100'.",
            "default": "50000-50100",
            "pattern": "^(\\d{1,5})-(\\d{1,5})$",
            "examples": [
                "50000-50100"
            ],
            "errorMessage": "Port range must be in the format 'lower-upper', where both sides are valid port numbers (1-65535) and the upper must be greater than the lower.",
            "internal": true
        },
        "communication.control_center_port": {
            "type": "integer",
            "description": "Port used by the control center.",
            "default": 54972,
            "minimum": 1,
            "maximum": 65535,
            "internal": true
        },
        "communication.user_defined_ip_timeout": {
            "type": "integer",
            "description": "Timeout (in milliseconds) for user-defined IP connections.",
            "default": 500,
            "minimum": 1,
            "internal": true
        },
        "communication.socket_read_timeout": {
            "type": "integer",
            "description": "Timeout (in milliseconds) for socket reads.",
            "default": 20000,
            "minimum": 1,
            "internal": true
        },
        "communication.heartbeat_timeout": {
            "type": "integer",
            "description": "Timeout (in milliseconds) for heartbeat signals.",
            "default": 5000,
            "minimum": 1,
            "internal": true
        }
    }
}

reset(key: str)¶

Resets the configuration value for the specified key to its default or initial value.

Parameters:

key (str) – The identifier for the configuration item to be reset.

Raises:

KeyError – If the key is not part of the configuration schema.
json.JSONDecodeError – if the configuration file is malformed and needs to be fixed manually.

Example:

#
# Reset a configuration value to its default by key
#
from typhoon.api.configuration import configuration

configuration.reset("control_center.hil_setup.custom_ip_addresses")
ip_addresses = configuration.get("control_center.hil_setup.custom_ip_addresses")

print(ip_addresses)

Output

[]

Sets the value of a configuration item identified by key.

Parameters:

key (str) – The identifier for the configuration item to be updated.
value (JSONSchemaType) – The new value to set for the configuration item. Must match the schema for the item.

Raises:

KeyError – If the key is not part of the configuration schema.
jsonschema.exceptions.ValidationError – if the value does not conform to the schema.
json.JSONDecodeError – if the configuration file is malformed and needs to be fixed manually.

Subscribe to configuration changes for a specific key.

Parameters:

key (str) – The identifier for the configuration item to subscribe to. It can also be partial (e.g., “general” or “general.autosave”).
handler (Handler) – Function to be called when the configuration item changes. The function accepts a single argument - a dictionary containing configuration keys and the updated values. If the key is partial (e.g., “general”), the dictionary will contain all the keys that start with “general”.
immediate (bool, optional) – If True, the handler will be called immediately with the current value of the configuration item, synchronously blocking only on the first call. If False, the handler will be called on the next configuration change.

Raises:

KeyError – If the key is not part of the configuration schema.

Example:

#
# Subscription example
#
from typhoon.api.configuration import configuration

def handler(c):
    print("Configuration changed: ", c)

configuration.subscribe("paths.user_lib_dir", handler)

# Include /home/user/typhoon/libs and all subdirectories in the search path for user libraries
directories = { "/home/user/typhoon/libs": True }
configuration.set("paths.user_lib_dir", directories)

# Clear the search path for user libraries
directories = {}
configuration.set("paths.user_lib_dir", directories)

# Unsubscribe from changes
configuration.unsubscribe("paths.user_lib_dir", handler)

Output

Configuration changed:  {'paths.user_lib_dir': {'/home/user/typhoon/libs': True}}
Configuration changed:  {'paths.user_lib_dir': {}}

property subscriber_thread¶

Get the subscriber thread which listens for configuration changes.

The thread is started as a daemon when the configuration API is first imported. It can be joined using the “join()” method to wait for it to finish.

Returns:: The subscriber thread.
Return type:: threading.Thread

Unsubscribe from configuration changes for a specific key.

Note

The same key and handler that were passed into the subscribe method must be used in order to unsubscribe.

Parameters:

key (str) – The identifier for the configuration item to unsubscribe from.
handler (Handler) – The function that was previously subscribed to the configuration item.

Configuration API¶

API references ¶

Table of Contents

Previous topic

This Page

Configuration API¶

API references¶

API references ¶