scriptDoc.txt

ScriptOnline
ScriptOnline.CredentialSourceKind(Enum)
The kinds of authentication allowed for the fallback to the default handler.

classScriptOnline.OnlineChangeOption(value)
Bases: Enum

Online change options used for multiple download.

Never= (0,)
Online change shall never be performed. In that case a full download is forced.

Try= (1,)
Online change shall be tried. If not possible, a full download shall be performed.

Force= (2,)
Online change shall be forced. If not possible, the action is terminated with no change.

Keep= 3
Try to login. Do not online update. Do not download. Keep as it is.

classScriptOnline.ApplicationState(value)
Bases: Enum

Execution state of an application.

none= (0,)
No valid application state (eg. not loaded).

run= (1,)
Application is running.

stop= (2,)
Application is stopped.

halt_on_bp= (3,)
Halted on a breakpoint.

debug_step= (4,)
Executing a single step in the debugger.

single_cycle= (5,)
Executing a single cycle in the debugger.

system_application= (255,)
TOCHECK maybe to delete, a special flag indicating a system application (only possible state is stop)

unknown= 65535
Unknown application state. uint.MaxValue, exact value depends on system

classScriptOnline.OperatingState(value)
Bases: Enum

The global state of an application. Although not defined as such, this enumeration is treated like a flags field, so the effective value may be a combination of more of these values.

none= (0,)
No application loaded.

program_loaded= (1,)
Program code is loaded (ready to execute)

download= (2,)
A download is in progress.

online_change= (4,)
Performing an online change.

store_bootproject= (8,)
Storing the bootproject.

force_active= (16,)
There are currently forced values for this application.

exception= (32,)
run_after_download= (64,)
Download code at the end of download is in progress (initialization of the application)

store_bootproject_only= (128,)
Only the bootproject is stored at download

exit= (256,)
Application exit is still executed (application is no longer active)

delete= (512,)
Application is deleted (object is available, but the content is stil deleted)

reset= (1024,)
Application reset is in progress

retain_mismatch= (2048,)
Retain mismatch occurred during loading the bootproject (retain data does not match to the application)

bootproject_valid= (4096,)
Bootproject available (bootproject matched to running application in RAM)

load_bootproject= (8192,)
Loading bootproject in progress

flow_active= (16384,)
flow control is active

run_in_flash= (32768,)
Application is running in flash only

core_dump_loaded= (131072,)
A Core-Dump for this application is loaded

executionpoints_active= (262144,)
there are Executionpoints active in the application

core_dump_creating= 524288
there are Executionpoints active in the application

classScriptOnline.ResetOption(value)
Bases: Enum

This enum defines the different kinds of reset (warm, cold, origin)

Warm= (0,)
Warm reset of the application - keep retain variables.

Cold= (1,)
“Cold” reset - keep persistent variables and applications

Original= 2
Reset “original” - erase all variables, applications, etc.

classScriptOnline.BlockDriverType(value)
Bases: Enum

An enumeration to specify the type of Block Driver used on the runtime system

Generic= (0,)
Any of the regular block drivers without special treatment or unknown

CmpBlkDrvTcp= (1,)
The Block Driver TCP in the runtime system

CmpBlkDrvCom= (2,)
The Block Driver COM in the runtime system

CmpBlkDrvUsb= (3,)
The Block Driver UDP in the runtime system

CmpBlkDrvShm= (4,)
The Block Driver Shared Memory in the runtime system

CmpBlkDrvUdp= (5,)
The Block Driver UDP in the runtime system

CmpBlkDrvCanClient= (6,)
The Block Driver CAN Client in the runtime system

CmpBlkDrvCanServer= (7,)
The Block Driver CAN Server in the runtime system

CmpBlkDrvDirectCall= (8,)
The Block Driver Direct Call in the runtime system

CmpBlkDrvDNS= 9
The Block Driver DNS in the runtime system

classScriptOnline.ParamType(value)
Bases: Enum

Enumeration defining allowed types for a gateway parameter. The types match the equally named .NET types.

SByte= (17,)
8 bit signed byte

Byte= (18,)
Unsigned byte (8 bit)

Int16= (19,)
16 bit signed integer

UInt16= (20,)
16 bit unsigned integer

Int32= (21,)
32 bit signed integer

UInt32= (22,)
32 bit unsigned integer

Int64= (23,)
64 bit signed integer

UInt64= (24,)
64 bit unsigned integer

Char= (25,)
A single character

Single= (26,)
Single precission FloatingPoint value

Double= (27,)
Double precission FloatingPoint value

Boolean= (28,)
Boolean value (true or false)

StringAnsi= (29,)
ASCII coded string

StringUnicode= 30
Unicode coded string.

classScriptOnline.AdditionalDirInfo(value)
Bases: Enum

Flags to get additional information about a file or directory.

None= (0,)
No information available

PlaceholderDirectory= (1,)
The directory is defined as a placeholder directory (e.g. $PlcLogic$) on the PLC.

RedundantDirectory= 2
The directory is a shortcut to another directory (e.g. links to a subdirectory in the default path)

classScriptOnline.ScriptOnline
Bases: object

Online functionality for the ScriptEngine.

Some of the commands may temporarily change the active application.

create_online_application(application=None)
Creates an online application.

To prevent resource leaks, script writers should wrap the usage of the online application in a with: block.

Parameters:
application (ScriptObject) – The application object to use. If this parameter is omitted, the active application is used.

Return type:
Before V3.5.0.0 ScriptOnlineApplication

Return type:
ScriptOnlineDevice

Returns:
The online application object.

propertyUNFORCE
Special value for unforcing a variable.

It is returned by ScriptOnlineApplication.get_prepared_value() and can be fed to ScriptOnlineApplication.set_prepared_value(). See also ScriptOnlineApplication.set_unforce_value().

Return type:
str

 propertyUNFORCE_RESTORE
Special value for unforcing and restoring a variable.

It is returned by ScriptOnlineApplication.get_prepared_value() and can be fed to ScriptOnlineApplication.set_prepared_value(). See also ScriptOnlineApplication.set_unforce_value().

Return type:
str

create_online_device(device=None)
Creates an online device.

To prevent resource leaks, script writers should wrap the usage
of the online device in a with: block.

type device:
ScriptObject

param device:
The application object to use. If this parameter is omitted, the device of the active application is

used. (This parameter is optional.)

rtype:
ScriptOnlineDevice

returns:
The online application object.

set_default_credentials(username, password=None)
Sets the default credentials for login to devices.

This setting is in effect until the end of the current script execution. Use None for the username and omit the password to delete the default credentials.

Version added:
3.5.3.0

Parameters:
username (str) – The username.

password (str) – The password.

set_specific_credentials(target, username, password=None)
Sets the default credentials for login to a specific device.

This setting is in effect until the end of the current script execution. Use None for the username and omit the password to delete the default credentials.

Version added:
3.5.3.0

Parameters:
target (object) – The target. You can pass a device object, an online device object, an application, or an online application. If you pass an application or online application, the setting will take effect for all applications in the corresponding device object.

username (str) – The username.

password (str) – The password.

clear_all_credentials()
Clears all credentials which were set by this script.

This only clears the cretentials at the level of the script. The online manager and other components may cache credentials internally, those caches are currently not cleared by this method.

Version added:
3.5.3.0

propertyauth_fallback_modes
Gets or sets the setting how authentication credentials are acquired when no default credentials are set, and no specific credentials match the target.

This setting is in effect until the end of the current script execution. By default, this is set to CredentialSourceKind.All. You can modify this value to disable interactive login.

Version added:
3.5.3.0

Return type:
CredentialSourceKind

 propertygateways
Gets all currently known gateways.

Version added:
3.5.8.0

Return type:
ScriptGateways

Returns:
A python tuple containing the gateways.

 propertygateway_drivers
Gets the gateway drivers.

Version added:
3.5.8.0

Return type:
ScriptGatewayDrivers

Returns:
A python tuple containing all gateway drivers.

register_trusts_certificate(device_object, callback, current_node_name=None)
Register a callback which allows to specify if the certificate of a PLC is trusted for the encrypted communication.

Version added:
3.5.17.0

Parameters:
device_object (ScriptObject) – Device object which provides the node name and Object GUID to get the TLS communication validator.

callback (TrustsCertificateCallback()) – Callback of the type TrustsCertificateCallback.

current_node_name (str) – Optional, node name of the PLC if the parameter device_object can’t provide the node name.

unregister_trusts_certificate(device_object, current_node_name=None)
Unregister a previously registered callback which allowed to specify if the certificate of a PLC is trusted for the encrypted communication.

Use the same parameters as from the registration process.

Version added:
3.5.17.0

Parameters:
device_object (ScriptObject) – Device object which provides the node name and Object GUID to get the TLS communication validator.

current_node_name (str) – Optional, node name of the PLC if the parameter device_object can’t provide the node name.

unregister_all_trusts_certificate()
Unregister all previously registered callbacks which allowed to specify if the certificate of a PLC is trusted for the encrypted communication.

Version added:
3.5.17.0

classScriptOnline.ScriptOnlineApplication
Bases: object

Online application object.

Some of the commands may temporarily change the active application.

This object keeps an internal connection to the device, so it should be disposed when you don’t need it any more: Call the Dispose() method when you’re done with it, or - even better - use the with statement. It will be automatically disposed when the script execution ends, but in long running scripts, you should dispose it yourself to prevent resource leaks, and other side effects of the open connection.

login(change_option, delete_foreign_apps)
Performs the application login.

If the application was logged in before, it will be logged out and a fresh login will be performed.

Parameters:
change_option (OnlineChangeOption) – The change option.

delete_foreign_apps (bool) – If set to True, delete foreign applications.

logout()
Logs this application out. If the application is not logged in, nothing happens.

propertyis_logged_in
Gets a value indicating whether this ScriptOnlineApplication is logged in.

Return type:
bool

Returns:
True if is logged in; otherwise, False.

start()
Starts this application.

Raises:
TimeoutException – In case of the operation taking to long.

stop()
Stops this application.

Raises:
TimeoutException – In case of the operation taking to long.

propertyapplication_state
Gets the application state.

Return type:
ApplicationState

 propertyoperation_state
Gets the operation status.

Return type:
OperatingState

create_boot_application()
Creates a boot application for this application on the device.

If the current application is not online, a file dialog asks the user for a path to write the boot file for. You may want to use ScriptApplication.create_boot_application() instead.

source_download()
Downloads the source archive to the device.

write_prepared_values()
Writes the prepared values.

Raises:
ValuesFailedException – If the write of some values fails.

force_prepared_values()
Forces the prepared values.

Raises:
ValuesFailedException – If the force of some values fails.

unforce_all_values()
Unforces all forced values for the current application.

Raises:
ValuesFailedException – If the unforce of some values fails.

get_prepared_value(expression)
Gets the prepared value for a given expression.

Parameters:
expression (str) – The expression

Return type:
str

Returns:
The prepared value, or None if nothing is prepared.

read_value(expression)
Gets the current value for a given expression.

Monitoring must be enabled.

Parameters:
expression (str) – The expression.

Return type:
str

Returns:
The value.

read_values(expressions)
Gets the current values for a list of expressions.

Monitoring must be enabled.

Parameters:
expressions (tuple[str]) – The expressions.

Return type:
list[str]

Returns:
The values.

get_prepared_expressions()
Gets all expressions for values currently prepared for this application (including those prepared by other scripts, editors etc).

Return type:
list[str]

Returns:
The prepared expressions.

get_forced_expressions()
Gets all expressions for values currently forced for this application (including those prepared by other scripts, editors etc).

Return type:
list[str]

Returns:
The forced expressions.

set_prepared_value(expression, value)
Prepares values the specified expression.

Use None or the empty string to unprepare the value.

Parameters:
expression (str) – The expression.

value (str) – The value.

set_unforce_value(expression, restore=False)
Prepares the specified forced expression for unforcing.

Parameters:
expression (str) – The expression.

restore (bool) – If set to true, the value is reset to the value before forcing.

propertytimeout
Gets or sets the timeout for some operations.

Some operations like start() have to wait for defined application states. If those operations take longer than this timeout, a TimeoutException is thrown. The default timeout is 60 seconds.

Return type:
int

reset(reset_option=ResetOption.Warm, force_kill=False)
Resets the online application. This also clears all breakpoints on the application (if any).

If the application is currently halted on a breakpoint, and the device supports to kill a task during the execution cycle (TargetProperties.TaskKillable), you can use the force_kill parameter to force the reset without running the current cycle to an end. If the device does not support TargetProperties.TaskKillable, this parameter will be ignored, and the current cycle will always be finished.

Version added:
3.5.0.0

Parameters:
reset_option (ResetOption) – The reset_option.

force_kill (bool) – Force the immediate kill of the application without finishing of the current cycle.

get_online_device()
Gets the online device for this application.

Return type:
ScriptOnlineDevice

propertyapplication
Gets the application object for this online application.

Return type:
ScriptObject

classScriptOnline.ScriptOnlineDevice
Bases: object

Functionality for manipulating online device objects.

All device objects for which the online manager returns a IOnlineDevice7 instance are extended with this methods.

This object keeps an internal connection to the device, so it should be disposed when you don’t need it any more: Call the Dispose() method when you’re done with it, or - even better - use the with statement. It will be automatically disposed when the script execution ends, but in long running scripts, you should dispose it yourself to prevent resource leaks, and other side effects of the open connection.

Version added:
3.5.0.0

reset_origin()
Reset the device to the origin (shipping) state.

For example, all plc applications, boot applications, and retain and persistent variables are deleted.

propertydevice
Gets the underlying device object for this online device.

Return type:
ScriptObject

connect()
Connects this instance. The connection is a shared connection to the device.

Please note that other actions like reset_origin may implicitly connect to the device.

Version added:
3.5.2.0

disconnect()
Disconnects this instance.

As the connection is shared, the underlying connection may actually stay open, for example when an application is still online.

Version added:
3.5.2.0

propertyconnected
Gets a value indicating whether this ScriptOnlineDevice is connected.

Version added:
3.5.2.0

Return type:
bool

 propertyshared_connected
Gets a value indicating whether this ScriptOnlineDevice or anything else has a shared connection to the device.

Version added:
3.5.2.0

Return type:
bool

Returns:
True if connected; otherwise, False.

forced_disconnect()
Forcibly disconnects all shared connections to the device (connections via online applications, as well as other connections), and resets the current login and session information.

Version added:
3.5.2.0

current_logged_on_username()
Gets the name of the user who is currently logged on in the device.

If None or an empty string is returned, nobody is logged on.

Version added:
3.5.2.0

Return type:
str

create_user_management(load_from_project=True)
Creates a new user management instance for this device.

For the devices with runtime V3.5.16.0 or newer you have to use create_live_user_management() because they only support the live user management.

Version added:
3.5.2.0

Parameters:
load_from_project (bool) – By default, the instance is initialized with the information stored in the device object in the current project. By setting this parameter to false, you can suppress this loading, e. G. if you want to load the user management via the ScriptDeviceUserManagement.upload() or ScriptDeviceUserManagement.load() methods.

Return type:
ScriptDeviceUserManagement

Returns:
The created user management instance.

Raises:
WrongDeviceUserManagementException – Thrown if the device only supports the live user management.

download_source(bCompact=False, additional_items=None)
Downloads the source archive to the device.

For a definition of the additional items, see ScriptProjectArchiveCategories. If you don’t pass any additional_items, ScriptProjectArchiveCategories.default is used. To exclude all additional items, explicitly pass None.

Version added:
3.5.4.0

Parameters:
bCompact (bool) – If True, the source archive will only contain the PLC and applications of the current device. If False, the source archive will contain all PLCs and all applications in the project.

additional_items (tuple[:class:`ScriptProjectArchiveCategory]) – The additional items to include in the project archive.

upload_source(archive_path)
Uploads the source from the device, and saves it under the specified output path.

This method will throw various Exceptions on errors.

Version added:
3.5.4.0

Parameters:
archive_path (str) – The local path where to save the project archive. (Usually ending with the extension .prj).

download_file(local_file, remote_file, force_overwrite)
Download a file to the PLC.

Version added:
3.5.9.0

Parameters:
local_file (str) – Path of the local file.

remote_file (str) – Path of the remote file.

force_overwrite (bool) – Force the overwrite if the remote file already exists.

upload_file(remote_file, local_file, force_overwrite)
Upload a file from the PLC.

Version added:
3.5.9.0

Parameters:
remote_file (str) – Path of the remote file.

local_file (str) – Path of the local file.

force_overwrite (bool) – Force the overwrite if the local file already exists.

rename_file(old_name, new_name)
Rename a file on the PLC.

Version added:
3.5.9.0

Parameters:
old_name (str) – Path of the remote file with the old name.

new_name (str) – Path of the remote file with the new name.

delete_file(remote_file)
Delete a file on the PLC.

Version added:
3.5.9.0

Parameters:
remote_file (str) – Path of the remote file.

create_directory(remote_directory)
Create a directory on the PLC.

Version added:
3.5.9.0

Parameters:
remote_directory (str) – Path of the new directory.

get_file_list_of_directory(remote_directory)
Read a directory on the PLC.

Version added:
3.5.9.0

Parameters:
remote_directory (str) – Path of the directory.

Return type:
tuple[ScriptDirectoryInfo]

Returns:
Array of info elements which describe the files and directories inside the given remote directory.

rename_directory(old_name, new_name)
Rename a directory on the PLC.

Version added:
3.5.9.0

Parameters:
old_name (str) – Path of the remote directory with the old name.

new_name (str) – Path of the remote directory with the new name.

delete_directory(remote_directory, recursive)
Delete a directory on the PLC.

Version added:
3.5.9.0

Parameters:
remote_directory (str) – Path of the remote directory.

recursive (bool) – If True, delete the directory resursively.

activate_license(ticket, url=None, license_names=None)
Performs a license activation on a remote device.

The first container returned be the device will be used for activation.

Version added:
3.5.10.0

Parameters:
ticket (str) – The ticket which contains the licenses.

url (str) – The license server. If None the default license server will be used.

license_names (tuple[str]) – The licenses which should be activated. If None or if no license is specified, every kind of license will be activated by default.

change_user_password(user, oldPassword, newPassword)
Update the passwort of a given user and reset the flag that the user must change the password on next login.

Version added:
3.5.14.0

Parameters:
user (str) – The user that shall be authentified.

oldPassword (str) – current password of the given user.

newPassword (str) – new password for the given user.

create_live_user_management()
Create a new live user management which is required by PLC runtime V3.5.16.0 or newer.

You have to create a connection before calling this method otherwise you get an exception. With SP16 or newer version of the PLC runtime you can access the user management only when connected.

Version added:
3.5.16.0

Raises:
WrongDeviceUserManagementException – Thrown if the device does not support the live user management.

Return type:
ScriptLiveDeviceUserManagement

set_credentials_for_initial_user(username, password, can_change_password=True, must_change_password=False)
Set the username and password for the initial user of the user management if the device requires it or you want one.

If the device requires an user management you need to specify an initial user otherwise you will get an exception. If it is not required and you don’t specify an initial user, no user management is created on the device.

Version added:
3.5.16.0

Parameters:
username (str) – Username of the initial user.

password (str) – Password of the initial user

can_change_password (bool) – User can change their password.

must_change_password (bool) – User must change their password with next login.

exceptionScriptOnline.ValuesFailedException
Bases: Exception

This exception is thrown by ScriptOnlineApplication.write_prepared_values() and ScriptOnlineApplication.force_prepared_values().

ValuesFailedException(failed_expressions)
Initializes a new instance of the ValuesFailedException class.

Parameters:
failed_expressions (list[str]) – The failed expressions.

Return type:
ValuesFailedException

propertyfailed_expressions
Gets the list of the failedexpressions.

Return type:
list[str]

classScriptOnline.ScriptGateway
Bases: object

Script engine representation of a configured gateway for runtime connections.

Version added:
3.5.8.0

propertyname
Gets the name of the gateway.

For backwards compatibility reasons, the gateway names are not guaranteed to be unique - several gateways with the same name may exist.

Return type:
str

 propertyguid
Gets the unique identifier of the gateway.

Version added:
3.5.8.0

Return type:
Guid

 propertygateway_driver
Gets the gateway protcol driver used for this gateway.

Version added:
3.5.8.0

Return type:
ScriptGatewayDriver

 propertyconfig_params
Gets a python dictionary with a copy of the current configuration of the gateway, using the ScriptGatewayParameterDescription.id as keys and the parameter values as values.

Version added:
3.5.8.0

Return type:
object

find_address_by_ip(address: IPAddress, port: int = 11740)
Finds an CODESYS address by scanning the network by IP or Hostname.

Currently, only IPv4 addresses are supported. This method blocks until either the device responded or the timeout for network scans is reached. Any exceptions coming form the communication layer will be thrown (e.g. if the Gateway is not running).

Version added:
3.5.8.0

Parameters:
address (IPAddress) – The IP address.

port (ushort) – The port.

Raises:
TimeoutException – Thrown in case no device replies.

Exception – Any other exception forwarded from the communication layer.

Return type:
string

Returns:
The CODESYS address.

perform_network_scan()
Performs a network scan on this gateway.

This method will block at least for the duration of the network scan timeout period.

Version added:
3.5.8.0

Raises:
Exception – Any exceptions occurring durint the network scan.

Return type:
tuple[ScriptScanTargetDescription]

Returns:
The list of devices which were found.

get_cached_network_scan_result()
Gets the cached result of the last network scan on this gateway.

Return type:
tuple[ScriptScanTargetDescription]

Returns:
The list of devices which were found.

classScriptOnline.ScriptScanTargetDescription
Bases: object

Description of a scan target found during a device scan.

Version added:
3.5.8.0

propertydevice_name
Gets the name of the device.

Example: “PLCFeeder”. If no name has been explicitly assigned to the device, it is derived from the corresponding router address, e.g. “@127.5”.

Return type:
str

 propertytype_name
Gets a string indicating the device type.

Example: “Beckhoff CX1000-100” or “BRC Motion Logic Controller”.

Return type:
str

 propertyvendor_name
Gets a string indicating the device vendor.

Example: “Beckhoff” or “BRC”

Return type:
str

 propertydevice_id
Gets the ID of the type to be matched with the installed device types (target descriptions).

Return type:
DeviceID

 propertyaddress
Gets the router address for this device.

A hierarchical addressing scheme is used. Example: “123.5”. Each component of the router address corresponds to an array element of the return value.

Return type:
str

 propertyparent_address
Get the router address of the parent node of this device.

Usually this will be the device address without the last address component. Is None if the parentAddress is unknown.

Return type:
str

 propertylocked_in_cache
If set to true, the devicedescription will stay in the gateways device cache, even during rebuild.

So this is not a property of the device itself but a property of the device description object and may be changed by plugins.

Return type:
bool

 propertyblock_driver
Property to access the type of block driver used for this target.

Return type:
BlockDriverType

 propertyblock_driver_address
Property to store and retrieve the driver-specific address for this target.

Return type:
str

classScriptOnline.ScriptGateways(iterable=(), /)
Bases: list

A collection of gateways currently configured in CODESYS.

Version added:
3.5.8.0

find_with_name(name)
Finds all gateways with the name.

Parameters:
name (str) – The name.

Return type:
list[ScriptGateway]

Returns:
A (possibly empty) sequence of all gateways with the name.

remove_gateway(guid: Guid)
Removes the specified gateway.

If the specified one is the default one, the next one (if any) will be the new default.

Parameters:
gateway – The guid of the gateway to remove.

add_new_gateway(name, parameters, driver=None, gateway_guid=None)
Creates and adds a new gateway.

The keys of the parameters dictionary need to be integers corresponding to the ScriptGatewayParameterDescription.id, the ScriptGatewayParameterDescription itself, or strings corresponding to the ScriptGatewayParameterDescription.name of the parameter (if the names are unique). The values will be converted using the convert_gateway_parameter() method.

Parameters:
name (str) – The name.

parameters (dict[int or str or ScriptGatewayParameterDescription, object]) – The gateway parameters (as a python dictionary).

driver (ScriptGatewayDriver) – The driver - if you don’t pass a driver, the default TCP/IP driver will be used.

gateway_guid (Guid or None) – The gateway guid - if None is passed, a new one will be generated.

Return type:
ScriptGateway

convert_gateway_parameter(parameter, paramType)
Converts an object to the specified gateway parameter type.

Parameters:
parameter (object) – The parameter.

paramType (ParamType) – Type of the parameter.

Return type:
obj

Returns:
The object converted to the specified ParamType.

classScriptOnline.ScriptGatewayDrivers(iterable=(), /)
Bases: list

Represents a list of script gateway drivers.

Version added:
3.5.8.0

find_with_name(name)
Finds all gateway drivers with the name.

Parameters:
name (str) – The name.

Return type:
list of ScriptGatewayDriver

Returns:
A (possibly empty) sequence of all gateway drivers with the name.

propertydefault_driver
Gets the default gateway driver (currently bound to TCP/IP on standard CODESYS and most derivates).

Return type:
ScriptGatewayDriver

classScriptOnline.ScriptGatewayDriver
Bases: object

Script engine representation of a gateway driver.

Version added:
3.5.8.0

propertyguid
A Guid that uniquely identifies the driver type.

Each implementation for a gateway driver is identified by a Guid.

Return type:
Guid

 propertyname
Get the user-readable name of this gateway driver.

Return type:
str

 propertygateway_parameters
Gets the gateway parameter descriptions - those are used when a new gateway with this driver is created.

Return type:
ScriptGatewayParameterDescriptions

Returns:
A collection containing the gateway parameters.

classScriptOnline.ScriptGatewayParameterDescriptions(iterable=(), /)
Bases: list

A collection of script gateway parameters.

Version added:
3.5.8.0

classScriptOnline.ScriptGatewayParameterDescription
Bases: object

Description of parameters for a gateway driver - those are used when a new gateway with this driver is created.

Version added:
3.5.8.0

propertyid
The id of the parameter.

The id is unique for any particular gateway driver.

Return type:
long

 propertyname
Human readable string, giving the name of the parameter.

Return type:
str

 propertydescription
Human readable string describing the parameter.

Return type:
str

 propertyparameter_type
The type of the parameter value.

The types here have finer granularity than the types
available in python. However, users don’t need to cast to the corresponding .NET types, this will be done by the script engine as long as the generic type kind is matching - e. G. a python integer is ok for all integer param types, or a single-character python string is ok for ParamType.Char.

Return type:
ParamType

 propertydefault_value
Default value of the parameter. May be None.

Return type:
object

validate(value)
Check whether the provided object is a valid value for this parameter.

You can use the ScriptGateways.convert_gateway_parameter() method to convert the parameter to the corresponding type.

Parameters:
value (object) – The value to check.

Raises:
Exception – If the object is not valid.

classScriptOnline.ScriptDirectoryInfo
Bases: object

Describes contents of a remote directory on the PLC.

Version added:
3.5.9.0

propertyname
Gets the name of the file/directory.

Return type:
str

 propertycreation_time
Get the creation time of the file/directory.

Return type:
DateTime

 propertylast_access_time
Get the last access time of the file/directory.

Return type:
DateTime

 propertylast_modification_time
Get the last modification time of the file/directory.

Return type:
DateTime

 propertyis_directory
Whether it is a directory.

Return type:
bool

 propertyis_file
Whether it is a file.

Return type:
bool

 propertysize
Get the file size in bytes.

Return type:
int

 propertyadditional_dir_info
Get the additional information of the file/directory.

Return type:
AdditionalDirInfo

ScriptOnline.TrustsCertificateCallback(certificate, chain, node_name)
This callback allows to specify if the certificate of a PLC should be trusted for the encrypted communcation.

Version added:
3.5.17.0

Parameters:
certificate (X509Certificate2) – Certificate of the PLC.

chain (X509Chain) – Chain of trust.

node_name (str) – Name of the PLC.

Return type:
bool

Returns:
True, if you trust the certificate.

ScriptExternalFileObject
classScriptExternalFileObject.ReferenceMode(value)
Bases: Enum

An enumeration.

Link= (0,)
LinkAndEmbed= (1,)
Embed= 2
classScriptExternalFileObject.AutoUpdateMode(value)
Bases: Enum

This enumeration is used to control how changes in a physical file are reflected to the embedded data of a _3S.CoDeSys.Core.External.IFileReference.

Always= (0,)
Changes on the physical file are automatically reflected in the embedded data.

Prompt= (1,)
When the physical file changes, an event will be triggered in order to obtain information whether to automatically update the embedded data or not.

Never= 2
Changes on the physical file are not automatically reflected in the embedded data.

classScriptExternalFileObject.ScriptExternalFileObjectMarker
Bases: object

Determines whether this object is an external file object or can contain them.

Version added:
3.5.9.0

propertyis_external_file_object
Gets a value indicating whether this ScriptObject is is an external file object.

Return type:
bool

Returns:
True if it is an external file object; otherwise, False.

 propertymay_contain_external_file_objects
Gets a value indicating whether this ScriptObject or ScriptProject may contain external file objects.

The project root may always contain external file objects, those are not downloaded to the devices. Devices and Applications may contain files which are synchronized to the runtime, depending on the device description and settings.

Return type:
bool

Returns:
True if it may contain external file objects; otherwise, False

classScriptExternalFileObject.ScriptExternalFileObject
Bases: ScriptExternalFileObjectMarker

Provides the actual functionality of the external file objects.

Version added:
3.5.9.0

propertyfile_path
Gets the file path.

Return type:
str

 propertyreference_mode
Gets the reference mode.

Return type:
ReferenceMode

 propertyauto_update_mode
Gets the auto update mode.

Return type:
AutoUpdateMode

change_modes(reference_mode, auto_update_mode=AutoUpdateMode.Never)
Changes the modes of the external file object.

Parameters:
reference_mode (ReferenceMode) – The reference mode.

auto_update_mode (AutoUpdateMode`) – The auto update mode. This is optional, and only makes sense if reference_mode is set to ReferenceMode.LinkAndEmbed. Defaults to AutoUpdateMode.Never if omitted.

update()
Updates this instance.

calculate_checksum()
Calculates the checksum of the data.

Return type:
int

Returns:
The CRC 32 value of the data.

propertylast_modification
Gets the last modification date.

Return type:
DateTime

 propertylength
Gets the length of the data in bytes.

Return type:
int

get_data(filename)
Gets the data by writing it to the specified filename.

Parameters:
filename (str) – The filename.

create_edit_path()
Gets the absolute path where this file reference is edited.

This is the absolute path itself if the file reference is linked to a file system object, or a temporary path if it is embedded into a project.

Return type:
str

Returns:
The edit path of this file reference.

classScriptExternalFileObject.ScriptExternalFileObjectContainer
Bases: ScriptExternalFileObjectMarker

This interface is implemented by the project root, and by objects which can contain synchable external file objects.

The project root may always contain external file objects, those are not downloaded to the devices. Devices and Applications may contain files which are synchronized to the runtime, depending on the device description and settings.

Version added:
3.5.9.0

create_external_file_object(file_path, name=None, reference_mode=ReferenceMode.Embed, auto_update_mode=AutoUpdateMode.Never)
Creates an external file objects with the specified name.

Parameters:
file_path (str) – The file path with the contents of the external file object.

name (str) – The name. This is optional, if it is omitted, the filename will be extracted from the path.

reference_mode (ReferenceMode) – The reference mode.

auto_update_mode (AutoUpdateMode) – The automatic update mode.

Return type:
ScriptExternalFileObject

Returns:
The newly created external file object.

ScriptProjects
classScriptProjects.PromptOverwriteResult(value)
Bases: Enum

Enum that enumerates the possible results for the overwrite handling.

Yes= 0
The user selected “Yes”, which means that the file or item should be overwritten.

No= 1
The user selected “No”, which means that the file or item should not be overwritten.

Cancel= 2
The user selected “Cancel”, which means that the project archive extraction should be terminated.

classScriptProjects.VersionUpdateFlags(value)
Bases: Enum

Flags for the _3S.CoDeSys.VersionCompatibilityManager.IVersionCompatibilityManager2.SetVersionUpdateFlags(_3S.CoDeSys.VersionCompatibilityManager.VersionUpdateFlags) method.

Regular= (0,)
The _3S.CoDeSys.VersionCompatibilityManager.IVersionCompatibilityManager checks for updates when opening a project and displays a related dialog for the user to manually update the versions.

NoUpdates= (1,)
The _3S.CoDeSys.VersionCompatibilityManager.IVersionCompatibilityManager will not check for updates when the next project will be opened. Therefore, there will be no dialog.

SilentMode= (2,)
Determines if a dialog for user interaction is shown or not. If this flag is set, there will be no dialog.

Remarks: This flag is often combined with one of the Update… flags.

UpdateAllCustomProviders= (4,)
The _3S.CoDeSys.VersionCompatibilityManager.IVersionCompatibilityManager will automatically update all items to the newest available version when the next project will be opened. To avoid a dialog, combine this flag with the _3S.CoDeSys.VersionCompatibilityManager.VersionUpdateFlags.SilentMode flag.

UpdateLibraries= (8,)
The _3S.CoDeSys.VersionCompatibilityManager.IVersionCompatibilityManager will automatically update all libraries to the newest available version when the next project will be opened. To avoid a dialog, combine this flag with the _3S.CoDeSys.VersionCompatibilityManager.VersionUpdateFlags.SilentMode flag.

UpdateCompiler= (16,)
The _3S.CoDeSys.VersionCompatibilityManager.IVersionCompatibilityManager will automatically update the compiler version to the newest available version when the next project will be opened. To avoid a dialog, combine this flag with the _3S.CoDeSys.VersionCompatibilityManager.VersionUpdateFlags.SilentMode flag.

UpdateVisualisation= (32,)
The _3S.CoDeSys.VersionCompatibilityManager.IVersionCompatibilityManager will automatically update the visualisation profile to the newest available version when the next project will be opened. To avoid a dialog, combine this flag with the _3S.CoDeSys.VersionCompatibilityManager.VersionUpdateFlags.SilentMode flag.

UpdateDevices= (64,)
The _3S.CoDeSys.VersionCompatibilityManager.IVersionCompatibilityManager will automatically update the device profile to the newest available version when the next project will be opened. To avoid a dialog, combine this flag with the _3S.CoDeSys.VersionCompatibilityManager.VersionUpdateFlags.SilentMode flag.

UpdateVisualisationStyles= (128,)
The _3S.CoDeSys.VersionCompatibilityManager.IVersionCompatibilityManager will automatically update the used visualization styles to the newest available versions when the next project will be opened. To avoid a dialog, combine this flag with the _3S.CoDeSys.VersionCompatibilityManager.VersionUpdateFlags.SilentMode flag.

UpdateUnresolvedUnboundPlaceholders= (256,)
The _3S.CoDeSys.VersionCompatibilityManager.IVersionCompatibilityManager will automatically redirect the unresolved unbound placeholders to the newest available versions when the next project will be opened. To avoid a dialog, combine this flag with the _3S.CoDeSys.VersionCompatibilityManager.VersionUpdateFlags.SilentMode flag.

UpdateAll= 65532
The _3S.CoDeSys.VersionCompatibilityManager.IVersionCompatibilityManager will automatically update all items to the newest available version when the next project will be opened. To avoid a dialog, combine this flag with the _3S.CoDeSys.VersionCompatibilityManager.VersionUpdateFlags.SilentMode flag.

Remarks: Please note that this enum value sets all bits in the range of 2 to 15 to “1”.

classScriptProjects.ScriptProjects
Bases: object

The ScriptDriverProjects uses this interface to provide project handling functionality for the python scripts.

create(path, primary=True)
Creates a new project.

Version added:
Parameters:
path (str) – The location where the project content is to be stored.

primary (bool or None) – if set to True the project will be the new primary project. See ScriptProject.primary for more information.

Return type:
ScriptProject

Returns:
The created ScriptProject instance.

open(path, password=None, primary=True, encryption_password=None, session_user=None, session_password=None, update_flags=VersionUpdateFlags.NoUpdates, allow_readonly=False)
Opens the specified project.

Warning

If a password is given, SystemInstances.ObjectManager must implement IObjectManager9, or a InvalidOperationException will be thrown (even if the project is not actually password protected).

If the password is omitted, None or empty string, opening a password protected archive will prompt the user for a password.

For the update_flags parameter, the VersionUpdateFlags.SilentMode is usually combined with one or more of the Update... flags defined in the VersionUpdateFlags enum. If you only pass some Update... flags without the VersionUpdateFlags.SilentMode flag, they will be used as initial values when the update dialog pops up. To silently update everything, you can pass the combination VersionUpdateFlags.SilentMode|VersionUpdateFlags.UpdateAll.

Parameters:
path (str) – The path of the project file to open.

password (str) – The password for the project encryption.

primary (bool) – if set to True, open as primary project. See ScriptProject.primary for more information.

encryption_password (str) – Version added: 3.5.5.0 The project encryption password.

session_user (str) – Version added: 3.5.5.0 The project session user (project usermanagement).

session_password (bool) – Version added: 3.5.5.0 The project session password (project usermanagement).

update_flags (VersionUpdateFlags) – Version added: 3.5.8.0 The flags telling whether some aspects (libraries, compiler version) ought to be updated when the project is loaded. The default is to silently update nothing.

session_password – Version added: 3.5.8.0 If set to True, allow the project to be opened as read-only.

Return type:
ScriptProject

Returns:
The opened project.

open_archive(archivefile, projectpath, overwrite=False, password=None, encryption_password=None, session_user=None, session_password=None, update_flags='VersionUpdateFlags.NoUpdates', prompt_absolute_path=None)
Opens a project archive.

The parameter projectpath will be evaluated using the following algorithm:

If it’s the path of an existing file, and overwrite is true, it will be overwritten.

If it’s the path to an existing file, and overwrite is false, an IOException will be thrown.

If this points to an existing directory, the project will be extracted with its original name into that directory.

If the path does not exist, but ends with a “/” or “", the directory (and all non-existing parent directories) will be created, then the project will be extracted with its original name into that directory.

If the path does not exist, but the parent directory exists, the given path (directory and file name) will be used.

Otherwise, if the path ends with “.project” or “.library”, the project will be extracted using the given path, creating all necessary parent directories.

In all other cases, a DirectoryNotFoundException will be thrown.

This method will return None when the archive extraction was cancelled due to an error, overwriting of files or cancel request for absolute path handling. If a password is given, SystemInstances.ObjectManager must implement IObjectManager9, or a MissingMethodException will be thrown (even if the project is not actually password protected). If the password is omitted, None or empty string, opening a password protected archive will prompt the user for a password.

For the update_flags parameter, the VersionUpdateFlags.SilentMode is usually combined with one or more of the Update... flags defined in the VersionUpdateFlags enum. If you only pass some Update... flags without the VersionUpdateFlags.SilentMode flag, they will be used as initial values when the update dialog pops up. To silently update everything, you can pass the combination VersionUpdateFlags.SilentMode|VersionUpdateFlags.UpdateAll.

Parameters:
archivefile (str) – The path of the project archive.

projectpath (str) – The path for the extracted project.

overwrite (bool) – if set to true, overwrite existing objects and project files

password (str) – The password.

encryption_password (str) – Version added: 3.5.5.0 The project encryption password.

session_user (str) – Version added: 3.5.5.0 The project session user (project usermanagement).

session_password (str) – Version added: 3.5.5.0 The project session password (project usermanagement).

update_flags (VersionUpdateFlags) – Version added: 3.5.8.0 The flags telling whether some aspects (libraries, compiler version) ought to be updated when the project is loaded. The default is to silently update nothing.

prompt_absolute_path (PromptAbsolutePath) – Version added: 3.5.16.0 The callback which allows to decide if an project archive item with an absolute path should be extracted relatively to the project file or not at all. Or if the operation should be canceled. The default is to cancel the operation.

Return type:
ScriptProject

Returns:
The opened project or null if it was canceled.

get_by_path(path)
Gets a Project by the absolute path where the project is physically stored.

Parameters:
path (str) – The path to the project.

Return type:
ScriptProject

Returns:
The project instance

propertyprimary
Gets the primary project, or None if no primary project currently exists.

The primary project is the one the user usually works with. See ScriptProject.primary for more information.

Version added:
Return type:
ScriptProject

 propertyall
Gets a (possibly empty) List of all currently opened projects.

Return type:
list[ScriptProject]

convert(path, output_path=None, converter=None, primary=True)
Converts the specified project.

Currently, password and device conversion prompts cannot be caught by the script.

Some converter guids are:¶
Guid

Description

{E3BC006A-5E3E-4f8f-AEE7-27FD1E0F2A3F}

CoDeSys for Automation Alliance project files (bevore V3.0, *.pro)

{941937BF-9A12-4174-814E-63D1523C94CC}

CoDeSys for Automation Alliance library files (before V3.0, *.lib)

Version added:
3.5.0.0

Parameters:
path (str) – The path of the project to convert.

output_path (str) – The output path. This parameter is optional, if it is omitted, the output path will be auto-generated from the project path by changing the file extension.

converter (str) – The GUID of the CoDeSys converter factory as string object. This parameter is optional, if omitted, the script engine will try to guess using the extension of the file name.

primary (bool) – If set to True, open as primary project. See ScriptProject.primary for more information.

Return type:
ScriptProject

Returns:
The converted project.

classScriptProjects.ScriptProjectArchiveCategories(iterable=(), /)
Bases: list

The list of available archive categories.

Enumerating this object will give all categories available in the current installation. Some often used categories are defined here, but may be unavailable (throw exceptions) in customized environments. An instance of this object is injected into the scriptengine module with the name “ArchiveCategories”.

propertydefault
The default selection of archive categories.

See also: ScriptProjectArchiveCategory.selected_by_default

Return type:
list[ScriptProjectArchiveCategory]

 propertynone
No categories (empty set).

This is a special sentinel value, different from passing an arbitrary empty list.

Return type:
list[ScriptProjectArchiveCategory]

 propertyall
A collection of all categories (returns self).

 propertycompileinfo
Gets the category for the compileinfo.

This is needed for logins and online changes into an existing application without download.

Return type:
ScriptProjectArchiveCategory

 propertylibraries
Gets the category for the libraries referenced by the project.

Return type:
ScriptProjectArchiveCategory

 propertydevices
Gets the category for the device descriptions of the devices used in the project.

Return type:
ScriptProjectArchiveCategory

 propertyoptions
Gets the category for the project, user, and machine specific preferences.

Return type:
ScriptProjectArchiveCategory

 propertyftd
Gets the category for the FDT Bulk Data.

Return type:
ScriptProjectArchiveCategory

 propertyimages
Gets the category for the imagepool images of the project.

Return type:
ScriptProjectArchiveCategory

 propertybootproject
Gets the category for the files containing offline boot applications, that were generated for the current project.

Return type:
ScriptProjectArchiveCategory

 propertylibraryprofile
Gets the category for the library profile that is currently in use with this project.

Return type:
ScriptProjectArchiveCategory

 propertyvisualstyles
Gets the category for the visualization styles which are currently referenced by this project.

Return type:
ScriptProjectArchiveCategory

 propertyvisualprofile
Gets the category for the active visualization profile.

Return type:
ScriptProjectArchiveCategory

 propertyvisuextensions
Gets the category for the active visualization extensions.

Return type:
ScriptProjectArchiveCategory

classScriptProjects.ScriptProjectArchiveCategory
Bases: object

Represents a category of items which can be included into a project archive.

propertyguid
Gets the Guid for this category.

Return type:
Guid

 propertyname
Gets a display name for this project category, e.g. “Referenced libraries”.

This string should be localized.

Return type:
str

 propertydescription
Gets a description for this project category.

This string should be localized.

Return type:
str

 propertyselected_by_default
Gets a boolean value indicating whether this category should be selected for project archive inclusion per default.

This is a hint for the presentation layer.

Return type:
bool

ScriptProjects.PromptAbsolutePath(self, path)
[Delegate]. This method can be used to decide if a project archive item with absolute path should be extracted relatively to the project file or not at all. Or if the whole operation should be canceled.

Parameters:
path (str) – Path to the location where the item wants to be extracted to

Return type:
PromptOverwriteResult

Returns:
Yes if the item should be extracted relatively to the project file. No if the item should not be extracted at all. Cancel if the operation should be canceled.

ScriptDeviceUserManagement
classScriptDeviceUserManagement.DeviceUserManagementFlags(value)
Bases: Enum

Flags for the entire _3S.CoDeSys.Core.Online.IDeviceUserList, the entire _3S.CoDeSys.Core.Online.IDeviceGroupList, a single _3S.CoDeSys.Core.Online.IDeviceUser, or a single _3S.CoDeSys.Core.Online.IDeviceGroup.

Edit= (1,)
If set, the particular _3S.CoDeSys.Core.Online.IDeviceUser or _3S.CoDeSys.Core.Online.IDeviceGroup can be edited.

AddMember= (2,)
If set, users or groups can be added to the particular _3S.CoDeSys.Core.Online.IDeviceGroup.

RemoveMember= (4,)
If set, users or groups can be removed from the particular _3S.CoDeSys.Core.Online.IDeviceGroup.

Create= (8,)
If set, new users can be created in the particular _3S.CoDeSys.Core.Online.IDeviceUserList, or new groups can be created in the particular _3S.CoDeSys.Core.Online.IDeviceGroupList.

Delete= (16,)
If set, existing users can be deleted from the particular _3S.CoDeSys.Core.Online.IDeviceUserList, or existing groups can be deleted from the particular _3S.CoDeSys.Core.Online.IDeviceGroupList

RemoveAllMembers= (32,)
If set, all existing users can be removed from the particular _3S.CoDeSys.Core.Online.IDeviceUserList. If not set, at least one user must be available in this group.

EditRights= (64,)
If set, permissions for the particular _3S.CoDeSys.Core.Online.IDeviceGroup can be changed

Owner= (128,)
If set, the particular _3S.CoDeSys.Core.Online.IDeviceGroup is the owner group

NameEditable= (256,)
If set, the name of the particular _3S.CoDeSys.Core.Online.IDeviceUser or _3S.CoDeSys.Core.Online.IDeviceGroup is editable.

PasswordUpToDate= (4096,)
If this flag is not set, a new password needs to be set by the user at the next login.

PasswordEditable= (8192,)
If this flag is set, the user can change his own password.

All= 4294967167
All flags together except flag Owner.

classScriptDeviceUserManagement.ScriptDeviceUserManagement
Bases: object

This object represents the user management on a given device.

propertyonline_device
Gets the online device this user management was created from.

Return type:
ScriptOnlineDevice

 propertyusers
Gets the users on the device.

Modifications of this list will take place offline and come into effect by downloading the user management to the device.

Return type:
ScriptDeviceUserList

 propertygroups
Gets the groups on the device.

Modifications of this list will take place offline and come into effect by downloading the user management to the device.

Return type:
ScriptDeviceGroupList

reload_from_program()
Reloads the user management contents from the device object in the project.

store_to_project()
Writes the current contents of the user management back to the device object in the project.

You should always use this method to persist your changes into the project. If you don’t call this method, the project will contain an outdated state.

upload()
Uploads the user and group information from the device.

download()
Downloads the user and group information to the device.

load(element: XmlElement)
Loads the contents of the given XML element into this user management object.

Parameters:
element (XmlElement) – The element.

save(writer=None)
Saves the contents of this user management object as XML into an System.Xml.XmlWriter.

Parameters:
writer (XmlWriter) – The writer.

classScriptDeviceUserManagement.ScriptDeviceUserList(iterable=(), /)
Bases: list

Represents a list of script device users.

propertyflags
Gets flags concerning the entire user list.

Return type:
DeviceUserManagementFlags

add(name)
Adds a new user with the specified name.

Parameters:
name (str) – The name of the new user.

Raises:
ArgumentException – A user with the specified name already exists.

NotSupportedException – Adding new users is not supported. Check flags for the DeviceUserManagementFlags.Create flag in advance.

Return type:
ScriptDeviceUser

Returns:
The newly created user.

remove(name)
Removes the user with the specified name.

Parameters:
name (str) – The name of the existing user.

Raises:
NotSupportedException –

Deleting existing users is not supported. Check ScriptDeviceUser.flags for the DeviceUserManagementFlags.Delete flag in advance.

Removing a member from a group in which the specified user is a member of is not supported. Check ScriptDeviceGroup.flags of all affected groups for the DeviceUserManagementFlags.RemoveMember flag in advance.

Return type:
bool

Returns:
True if the user existed and was removed, otherwise False

clear()
Removes all users.

Raises:
NotSupportedException – Deleting existing users is not supported. Check ScriptDeviceUser.flags for the DeviceUserManagementFlags.Delete flag in advance. –OR– Removing a member from a group in which the specified user is a member of is not supported. Check ScriptDeviceGroup.flags of all affected groups for the DeviceUserManagementFlags.RemoveMember flag in advance.

classScriptDeviceUserManagement.ScriptDeviceGroupList(iterable=(), /)
Bases: list

A list of groups on the device.

propertyflags
Gets flags concerning the entire group list.

Return type:
DeviceUserManagementFlags

add(name)
Adds a new group with the specified name.

Parameters:
name (str) – The name of the group.

Return type:
ScriptDeviceGroup

Returns:
The newly created group, or None if a group with the specified name already exists.

remove(name)
Removes the group with the specified name.

Parameters:
name (str) – The name of the existing group.

Return type:
bool

Returns:
True if the group existed and was removed, otherwise False

clear()
Removes all groups.

classScriptDeviceUserManagement.ScriptDeviceUser
Bases: object

An user on this device.

propertyflags
Gets flags concerning this particular user.

Return type:
DeviceUserManagementFlags

 propertyname
Gets or sets the name of the user.

Raises:
NotSupportedException – Editing this user is not supported. Check flags for the DeviceUserManagementFlags.Edit flag in advance.

ArgumentException – A user with the specified name already exists.

Return type:
str

set_password(password)
Sets the password for this user.

Parameters:
password (str) – The password to set.

propertypassword_hash
Gets or sets the encrypted password for this user.

Raises:
NotSupportedException – Editing this user is not supported. Check flags for the DeviceUserManagementFlags.Edit flag in advance.

Return type:
str

set_user_flags(flags)
Sets flags for the user.

Parameters:
flags (DeviceUserManagementFlags) – The flags to set.

classScriptDeviceUserManagement.ScriptDeviceGroup
Bases: object

A group of users, which have common rights on the device.

propertyflags
Gets flags concerning this particular group.

Return type:
DeviceUserManagementFlags

 propertyname
Gets or sets the name of the group.

Raises:
NotSupportedException – Editing this user is not supported. Check flags for the DeviceUserManagementFlags.Edit flag in advance.

ArgumentException – A group with the specified name already exists.

Return type:
str

 propertyuser_members
Gets the list of all user names which are members of this group.

This list can be modifed in-place to add or remove users from this group.

Return type:
list[string]

 propertygroup_members
Gets the list of all group names which are members of this group.

This list can be modifed in-place to add or remove groups from this group.

Return type:
list[str]

check_cyclic_membership(new_group_member)
Checks whether adding the specified group member would cause a cyclic membership dependency.

Parameters:
new_group_member (str) – The name of the new group membership to check.

Return type:
bool

Returns:
True if adding the specified group member would cause a cycle, otherwise False.

ScriptDeviceDescription
classScriptDeviceDescription.ScriptDeviceCollection(iterable=(), /)
Bases: list

A collection of ScriptDeviceDescription objects.

propertyvendors
Gets the list of all vendors in the collection.

Return type:
tuple[int]

get_devices_of_vendor(vendor)
Get all devices in the list which match the specified vendor.

Parameters:
vendor (str) – Vendor name.

Return type:
ScriptDeviceCollection

Returns:
A collection of devices from one vendor.

classScriptDeviceDescription.ScriptDeviceDescription
Bases: object

Description of a device.

propertydevice_id
Get the identification object of the device.

Return type:
DeviceID

Returns:
DeviceID

 propertydevice_info
Get information about the device.

Return type:
ScriptDeviceInfo

Returns:
DeviceInfo

 propertyconnectors
Gets the connectors.

Return type:
ScriptDeviceConnectorSet

Returns:
DeviceConnectorSet

 propertyname
Internationalized name of the device.

Return type:
str

 propertydescription
Internationalized description of the device.

Return type:
str

 propertyvendor
Internationalized vendor of the device vendor.

Return type:
str

 propertycategories
Gets a list of categories this device belongs to.

Return type:
tuple[int]

 propertyfamilies
Gets a list of vendor-specific families this device belongs to.

Each string has got the format VendorId:FamilyId.

Return type:
tuple[str]

 propertycustom
Get vendor specific information for the device.

This property may contain all kinds of information not defined by the specification, structured as an XML-Fragment with root node “Custom”.

Example::
<Custom><MaxTemp>30</MaxTemp></Custom>\

Return type:
str

 propertyorder_number
Vendor specific order number for this device.

Return type:
str

 propertydefault_instance_name
The default intance name for this device.

Version added:
3.5.11.0

Return type:
str

classScriptDeviceDescription.ScriptVendorDescription
Bases: object

Vendor description.

propertyvendor_id
Id of the vendor.

Return type:
int

 propertyversion
Version.

Return type:
str

 propertyvendor_info
Vendor information.

Return type:
ScriptVendorInfo

 propertyfamilies
Get all families of the vendor.

Return type:
tuple[ScriptDeviceFamily]

get_family(family_id)
Get the family with the specified family Id.

Parameters:
family_id (int) – Family Id.

Return type:
ScriptDeviceFamily

Returns:
Device family object or None if there is no matching family.

classScriptDeviceDescription.ScriptVendorInfo
Bases: object

Vendor information.

propertyname
Vendor name.

Return type:
str

 propertyaddresses
Address of the vendor.

Return type:
tuple[str]

 propertyphones
Phone number(s).

Return type:
tuple[str]

 propertyfaxes
Fax number(s).

Return type:
tuple[str]

 propertymail_addresses
eMail address(es).

Return type:
tuple[str]

 propertyweb_addresses
Web address(es).

Return type:
tuple[str]

classScriptDeviceDescription.ScriptDeviceFamily
Bases: object

Family Id.

propertyfamily_id
Family Id.

Return type:
int

 propertyparent_family
Parent family.

Return type:
str

 propertyname
Family name.

Return type:
str

 propertydescription
Description of the family.

Return type:
str

 propertysub_families
Sub families of the family.

Return type:
tuple[ScriptDeviceFamily]

ScriptLibManObject
classScriptLibManObject.LibManager
Bases: object

An instance implementing this interface is injected into the scriptengine scope under the name library manager.

propertyrepositories
Gets the list of available library repositories.

The order of those repositories is configurable by the user in the dialog and the script.

This list is a snapshot of the current state. When repositories are created, removed or moved, those changes are not reflected “live” in the list, and you need to get a fresh copy.

Return type:
tuple[LibRepository]

Returns:
The list of available repositories.

insert_repository(rootfolder, name, index=-1)
Creates a new library repository.

Parameters:
rootfolder (str) – The rootfolder for the repository (this must be the full path to an existing directory on disk).

name (str) – The name of the repository.

index (int) – The index of the repository in the list. -1 means the repository is added to the end of the list.

Return type:
LibRepository

Returns:
The newly created repository.

move_repository(repository, new_index)
Move_repositories the specified repository to a new position in the list.

Use this to manipulate the search order.

Parameters:
repository (LibRepository) – The repository.

new_index (int) – The new index. You can pass -1 to move it to the end of the list.

remove_repository(repository, delete_on_disk=False)
Removes the specified repository.

Parameters:
repository (LibRepository) – The repository.

delete_on_disk (bool) – If set to True, the on-disk directory is also deleted.

update_repository(repository, new_name=None, new_location=None, copy_libraries=False)
Update the specified repository.

Parameters:
repository (LibRepository) – The repository.

new_name (str) – The new name.

new_location (str) – The new location.

copy_libraries (bool) – if set to True, the libraries from the old location are installed at the new location, if they don’t exist.

get_file_path(library)
Gets the file path of the specified library in the library repository.

Parameters:
library (ManagedLib) – The library.

Return type:
str

Returns:
The file path of the library.

propertycategories
Gets all the known library categories.

Return type:
tuple[LibCategory]

Returns:
All the known library categories.

 propertytop_level_categories
Gets the all known top level library categories.

Return type:
tuple[LibCategory]

Returns:
All known top level library categories.

get_category(guid)
Gets the category with the specified GUID.

Parameters:
guid (Guid) – The GUID.

Return type:
LibCategory

Returns:
The library category.

install_library(filepath, repository=None, overwrite=False)
Installs the library with the specified filepath.

Parameters:
filepath (str) – The filepath of the library to install.

repository (LibRepository) – The repository. This parameter is optional, if omitted, the first repository in the list is used.

overwrite (bool) – if set to True, existing libraries are replaced.

Return type:
ManagedLib

Returns:
The installed library.

uninstall_library(repository, library)
Uninstalls a library from the specified repository.

Parameters:
repository (LibRepository) – The repository.

library (ManagedLib) – The library.

get_library(name, repository)
Gets all libraries with the specified name.

Parameters:
name (str) – The name.

repository (LibRepository) – The repository. If you pass None, all repositories are searched in order.

Return type:
ManagedLib

Returns:
The found library.

get_all_libraries(exclude_shadowed_libs: bool = True)
This override is used when parameter is of type bool.

Gets all libraries.

Parameters:
exclude_shadowed_libs (bool) – If set to True, shadowed libs are excluded.

Return type:
tuple[ManagedLib]

find_library(display_name)
Finds the library with the specified display_name.

Parameters:
display_name (str) – The display name to search for.

Return type:
tuple [ManagedLib, LibRepository]

Returns:
A python tuple containing the ManagedLib and the LibRepository, or None if nothing found.

classScriptLibManObject.LibRepository
Bases: object

Description class for a library repository.

propertyeditable
Gets a value indicating whether this LibRepository is editable.

The default system library repository is not editable - that means, it cannot be removed from the list of repositories.

Return type:
bool

Returns:
True if editable, otherwise False.

 propertyname
Gets the name of the repository.

Return type:
str

 propertyroot_folder
Gets the root folder of the repository.

Return type:
str

classScriptLibManObject.ManagedLib
Bases: object

Description class for a managed library.

propertydisplayname
Display name.

Return type:
str

 propertycompany
Company.

Return type:
str

 propertytitle
Title.

Return type:
str

 propertyversion
Version.

Return type:
Version

 propertydefault_namespace
Default namespace.

Return type:
str

 propertydependencies
Gets the dependencies as a list of strings.

Return type:
tuple[str]

 propertycategories
Gets the categories.

Gets the list of LibCategory.

Return type:
tuple[LibCategory]

classScriptLibManObject.LibCategory
Bases: object

Information about a library category.

propertyguid
Gets the guid identifying the category.

Return type:
Guid

 propertyparent
Gets the parent category, or None if the category is top level.

Return type:
LibCategory

 propertydefault_name
Gets the default name.

Return type:
str

 propertyname
Gets the localized name, or the default name if no localized name is available.

Return type:
str

 propertylocalized_name
Gets the localized name for the current UI culture.

Return type:
str

 propertyversion
Version.

Return type:
Version

classScriptLibManObject.ScriptLibManObjectMarker
Bases: object

Every ScriptObject instance will be extended with this method.

Version added:
3.4.3.0

propertyis_libman
Gets a value indicating whether this instance is a lib man object.

Return type:
bool

Returns:
True if this instance is lib man object, otherwise False.

classScriptLibManObject.ScriptLibManObject
Bases: ScriptLibManObjectMarker

Functionality for manipulating library managers.

All objects implementing LibManObject will be extended with this methods.

get_libraries(recursive=False)
Returns a list of all libraries.

Parameters:
recursive (bool) – If set to True, sublibraries are also queried recursively.

Return type:
list [str]

Returns:
The list of library names.

add_library(library: ManagedLib)
Adds a reference to the specified library.

Parameters:
library (ManagedLib) – The library (since V3.5.5.0).

add_placeholder(name: str, default_resolution: ManagedLib)
Adds a placeholder with the specified default resolution.

Parameters:
name (str) – The name.

default_resolution (ManagedLib) – The default resolution (since V3.5.5.0).

remove_library(name)
Removes the librariy with the specified name.

Parameters:
name (str) – The name.

propertyreferences
Gets the collection of the references currently configured within this library manager.

Version added:
3.5.5.0

Return type:
ScriptLibraryReferences

classScriptLibManObject.ScriptLibraryReferences(iterable=(), /)
Bases: list

The references currently managed by the library manager.

classScriptLibManObject.ScriptLibraryReference
Bases: object

A library reference in the library manager.

propertyid
Id.

Return type:
int

 propertyis_placeholder
Gets a value indicating whether this ScriptLibraryReference is a placeholder.

Return type:
bool

Returns:
True if it is a placeholder, otherwise False.

 propertyis_managed
Gets a value indicating whether this ScriptLibraryReference is a managed reference to a fixed library version.

Return type:
bool

 propertyname
Gets the name of this library.

For managed items, this follows the pattern “Name, Version (Company)”. For placeholder items, this name follows the pattern “#Name”. See also: ScriptPlaceholderReference.placeholder_name.

Return type:
str

 propertynamespace
Gets or sets the namespace for this library.

Return type:
str

 propertysystem_library
Gets a boolean value indicating whether this library is a system library or not.

System libraries have been added implicitly by plug-ins whereas non-system libraries have been explicitly added by the user.

Return type:
bool

get_dependencies()
Gets the dependencies of this library.

For libraries containing cyclic dependencies, this may lead to an endless recursion.

Return type:
list[ScriptLibraryReference]

Returns:
A list of dependencies.

propertyparameters
Gets the library parameter set.

If a global variable list containing only constant values has the attribute ‘parameterlist’, its content may be modified in the referencing project using this mechanism.

Return type:
ScriptLibraryParameters

 propertyhide_when_referenced_as_dependency
Gets or sets a value indicating whether this library node should be hidden in the user interface if it a direct or indirect dependency of a top-level library node.

Return type:
bool

 propertypublish_symbols_in_container
Gets or sets the qualified-only flag.

If set, the name of the library is mandatory for any access to the library content.

The default is true.

Return type:
bool

 propertyqualified_only
Gets or sets the qualified-only flag.

If set, the name of the library is mandatory for any access to the library content.

Defaults to True.

Return type:
bool

 propertyoptional
Gets or sets the optional flag.

Libraries which are optional are not reported to the user as missing if they do not exist.

Return type:
bool

classScriptLibManObject.ScriptManagedLibraryReference
Bases: ScriptLibraryReference

A managed library reference which points to a fixed version of the library.

ScriptLibraryReference.is_managed is true for those instances.

propertymanaged_library
Gets the managed library.

Return type:
ManagedLib

classScriptLibManObject.ScriptPlaceholderReference
Bases: ScriptLibraryReference

A placeholder reference. :class`ScriptLibraryReference` instances with ScriptLibraryReference.is_placeholder == True implement this interface.

propertyplaceholder_name
Gets the name of the placeholder.

In contrast to ScriptLibraryReference.name, this name does not include the leading ‘#’ character.

Return type:
str

 propertydefault_resolution
Gets or sets the default resolution of the library.

Return type:
str

 propertyeffective_resolution
Effective resolution.

Return type:
str

 propertyis_redirected
Gets a value indicating whether this ScriptPlaceholderReference is redirected.

Return type:
bool

get_redirection()
Gets the redirection setting for this library.

Return type:
str

Returns:
The redirection.

set_redirection(fixed_resolution='')
Sets the redirection for this library.

Parameters:
fixed_resolution (str) – The fixed resolution. Use None or an empty string to delete the redirection.

propertyresolution_info
Gets a human readable information how this placeholder is resolved.

Return type:
str

 propertyresolver_guid
Gets a machinable readable information how this placeholder is resolved.

Return type:
Guid

classScriptLibManObject.ScriptLibraryParameters(iterable=(), /)
Bases: list

The library parameters interface. This is a sequence of the parameter names.

If a global variable list containing only constant values has the attribute ‘parameterlist’, its content may be modified in the referencing project using this mechanism.

classScriptLibManObject.ScriptLibManObjectContainer
Bases: object

Projects and Application Objects are extended with this interface.

Version added:
3.5.2.0

propertyhas_library_manager
Gets a value indicating whether this ScriptLibManObjectContainer has a library manager.

Return type:
bool

Returns:
True if there is a library manager, otherwise False.

get_library_manager()
Gets the library manager for this application or project, implicitly creating one if none is existing yet.

Return type:
ScriptObject

Returns:
The library manager object. (ScriptObject)

ScriptExplicitConnectorObjects
classScriptExplicitConnectorObjects.ScriptExplicitConnectorObjectsMarker
Bases: object

Decorator for marking an object as explicit connector or not.

All objects within a project are decorated with this marker since V3.5.4.0.

Version added:
3.5.4.0

propertyis_explicit_connector
Gets a value indicating whether this instance is a device object.

Return type:
bool

Returns:
True if this instance is device object; otherwise, False.

classScriptExplicitConnectorObjects.ScriptExplicitConnectorObject
Bases: ScriptExplicitConnectorObjectsMarker, ScriptConnector

Decorator for explicit connector objects.

All objects within a project which are explicit connector objects are extended with this interface (since V3.5.4.0).

Version added:
3.5.4.0

allowed_interfaces_at(index)
Get the name of the child interfaces that this device object can accept at the specified insert position.

Parameters:
index (int) – The child index where a device should be inserted.

Return type:
list[str]

Returns:
A list of possible interface names or None if no device can be inserted at that position.

insert(name: str, index: int, type: int, id: str, version: str, module: Optional[str] = None)
Inserts the specified device at the specified index.

Parameters:
name (str) – Name of the device.

index (int) – index where to insert the device.

type (int) – The device type.

id (str) – The device identification.

version (str) – The device version.

module (str) – The module ID.

add(name: str, type: int, id: str, version: str, module: Optional[str] = None)
Adds the specified device.

Parameters:
name (str) – Name of the device.

type (int) – The device type.

id (str) – The device identification.

version (str) – The device version.

module (str) – The module ID.

export_io_mappings_as_csv(file_path)
Export the io mappings as a CSV file to the specified absolute path.

Parameters:
file_path (str) – The absolute path of the file to export.

import_io_mappings_from_csv(file_path)
import the io mappings from a CSV file at the specified absolute path.

Parameters:
file_path (str) – The absolute path of the file to import.

propertydriver_info
Get the driver info of the explicit connector.

Version added:
3.5.15.0

Return type:
ScriptDriverInfo

ScriptUserManagement
classScriptUserManagement.ObjectPermissionKind(value)
Bases: Enum

This enumeration contains the various possibilites to access an object from the viewpoint of the User Management.

View= (0,)
The permission to view an object.

Modify= (1,)
The permission to modify an object.

Remove= (2,)
The permission to remove an object.

AddRemoveChildren= 3
The permission to add or remove a child to or from an object.

classScriptUserManagement.PermissionState(value)
Bases: Enum

The permission state, either “granted”, “denied”, or “default”.

Granted= (0,)
The corresponding permission is explicitely granted to a certain group.

Denied= (1,)
The corresponding permission is explicitely denied to a certain group.

Default= 2
The corresponding permission is not explicitely set for a certain group.

classScriptUserManagement.ScriptUserManagement
Bases: object

UserManagement interface.

propertyproject
Backlink to the project for this user management.

Return type:
ScriptProject

 propertyusers
The collection of all defined users for this project.

Return type:
ScriptUserList

 propertygroups
The colleciton of all defined groups for this project.

Return type:
ScriptGroupList

 propertylogged_on_user
Gets the user which is currently logged in, or None if no user is currently logged in.

Return type:
ScriptUser

 propertylogin_time
Gets the timestamp since the last successful login, or DateTime.MinValue if no user is currently logged in.

Return type:
DateTime

login(username, password)
Log into the project using the specified credentials.

This is equal to ScriptProject.login().

Parameters:
username (str) – The username.

password (str) – The password.

logout()
Log out from the project (back to the user “nobody”).

This is equal to ScriptProject.logout().

check_available(type)
Checks whether permission management for the given PermissionType is available in the given CoDeSys installation.

Parameters:
type (Guid) – The type.

Return type:
bool

get_user_management_permission()
Gets the permission object for the user management.

Return type:
ScriptPermission

get_command_permission(commandguid)
Gets the permission object for execution of a specific command.

Parameters:
commandguid (Guid or ScriptCommand) – The ScriptCommand or its Guid.

Return type:
ScriptCommandPermission

Returns:
The command permission object.

get_factory_permission(factory)
Gets the permission object for accessing a specific object factory.

Parameters:
factory (Guid or ScriptObjectFactory) – The factory or its guid.

Return type:
ScriptFactoryPermission

Returns:
The factory permission object.

get_object_permission(obj, kind)
Gets a Permission object for that specific script object.

Parameters:
obj (ScriptObject) – The object we want the permission for.

kind (ObjectPermissionKind) – The kind of object access permission we want.

Return type:
ScriptObjectPermission

Returns:
The ScriptObject.

propertytypes
Gets all available types.

Return type:
ScriptPermissionTypes

classScriptUserManagement.ScriptPermissionTypes(iterable=(), /)
Bases: list

This object represents all available permission types.

propertyusermanagement
The permission type guid for user management, or Guid.Empty if not available in this installation.

Return type:
Guid

 propertyobjectaccess
The permission type guid for object access rights, or Guid.Empty if not available in this installation.

Return type:
Guid

 propertyobjectfactory
The permission type guid for object factory rights (object creation), or Guid.Empty if not available in this installation.

Return type:
Guid

 propertycommandexecution
The permission type guid for execution of commands, or Guid.Empty if not available in this installation.

Return type:
Guid

classScriptUserManagement.ScriptUserList(iterable=(), /)
Bases: list

Represents the list of all users known to the current project.

propertyuser_management
Back-Link to the project’s user management.

Return type:
ScriptUserManagement

 propertyproject
Backlink to the project for this user management.

Return type:
ScriptProject

create(name)
Creates a new user with the specified name.

Parameters:
name (str) – The name.

Return type:
ScriptUser

classScriptUserManagement.ScriptUserOrGroup
Bases: object

This interface contains the common members of ScriptUser and ScriptGroup.

propertyproject
Backlink to the project for this user management.

Return type:
ScriptProject

 propertyuser_management
Back-Link to the project’s user management.

Return type:
ScriptUserManagement

 propertyis_user
Gets a value indicating whether this ScriptUserOrGroup is an user.

Return type:
bool

 propertyis_group
Gets a value indicating whether this ScriptUserOrGroup is a group.

Return type:
bool

 propertyid
Gets the ID of this user or group.

Return type:
Guid

 propertyname
Gets the login name of this user or group.

Return type:
str

 propertydescription
Gets or sets the description for this user or group. This is informative only.

Return type:
str

add_to(parent)
Adds this user or group to the specified parent group.

Parameters:
parent (ScriptGroup) – The parent.

remove_from(parent)
Removes this user or group from the specified parent group.

Parameters:
parent (ScriptGroup) – The parent.

classScriptUserManagement.ScriptUser
Bases: ScriptUserOrGroup

Instances of this interface represent a single user within the user management.

A user is uniquely identified by its ID (not by its name), although its name must also be unique within a user list.

propertyuserlist
Backreference to the user list.

Return type:
ScriptUserList

 propertyfullname
Gets or sets the full name of this user. This is informative only.

Return type:
str

 propertyactive
Gets or sets a boolean which indicates whether this user is currently active.

Inactive users cannot login to the user management.

Return type:
bool

check_password(password)
Checks the password for an user.

Parameters:
password (str) – The password.

Return type:
bool

Returns:
True if the password is correct.

change_password(old_password, new_password)
Changes the password for the user.

Parameters:
old_password (str) – The old password.

new_password (str) – The new password.

remove()
Removes the user with the specified ID from this list.

Raises:
UserNotExistingException – If the user does not exist (e. G. because it was removed before).

CannotRemoveLastMemberFromOwnerGroupException – If the user is the last member of the owner group.

rename(newname)
Renames the user.

Parameters:
newname (str) – The new name.

propertygroups
Gets a python tuple with the groups this user is member of.

Return type:
tuple[ScriptGroup]

classScriptUserManagement.ScriptGroupList(iterable=(), /)
Bases: list

Represents the list of all known groups in this project.

propertyuser_management
Back-Link to the project’s user management.

Return type:
ScriptUserManagement

 propertyproject
Backlink to the project for this user management.

Return type:
ScriptProject

create(name)
Creates a new group with the specified name.

Parameters:
name (str) – The name.

Return type:
ScriptGroup

Returns:
The newly created group.

propertyowner_group
Owner group.

Return type:
ScriptGroup

 propertyeveryone_group
Everyone group.

Return type:
ScriptGroup

classScriptUserManagement.ScriptGroup
Bases: ScriptUserOrGroup

Instances of this interface represent a single group within the user management.

A group is uniquely identified by its ID (not by its name), although its name must also be unique within a group list.

propertygrouplist
Backlink to the grouplist.

Return type:
ScriptGroupList

add_member(member)
Adds a member to this group. This might be either a user or another group.

If such a user or group does not exist, (e. G. because it was deleted in the meantime), a UserNotExistingException, GroupNotExistingException, or UserOrGroupNotExistingException is thrown. If the user or group is already a member of this group, a UserIsAlreadyMemberOfGroupException or GroupIsAlreadyMemberOfGroupException is thrown.

Parameters:
member (ScriptUserOrGroup) – The user or group.

Raises:
GroupCycleException – If this addition would cause a membership cycle.

remove_member(member)
Removes a member from this group.

Parameters:
member (ScriptUserOrGroup) – The member.

has_member(member)
Checks whether the specified user or group is a member of this group.

Parameters:
member (ScriptUserOrGroup) – The member.

Return type:
bool

Returns:
True if the specified user or group is member of this group, otherwise False.

get_user_members(recursive)
Returns a python tuple of all users which are member of this group, or which are members of group members of this group.

Parameters:
recursive (bool) – if set to True, includes users which are members of group members of this group.

Return type:
list

Returns:
A python tuple of ScriptUser objects.

get_group_members()
Gets a python tuple of all groups which are member of this group.

Return type:
list

propertyis_everyone_group
Gets a boolean value indicating whether this group is the “everyone” group.

Return type:
bool

 propertyis_owner_group
Gets a boolean value indicating whether this group is the “owner” group.

Return type:
bool

rename(newname)
Renames the group.

Parameters:
newname (str) – The new name.

remove()
Removes this group from the containing grouplist.

classScriptUserManagement.ScriptPermission
Bases: object

Interface for permission objects.

propertytype
Gets the type.

Return type:
Guid

check_permission(silent_or_group)
This overload is used when silent_or_group is of type bool.

Checks whether the currently logged in user has a specific permission or not.

Parameters:
silent (bool) – If of type bool: If False, when the permission is not granted, the RequestAuthorization event is triggered which typically prompts a new login interactively and the permission is checked again with the new login. If True, nothing will be prompted.

Return type:
bool

Returns:
True if the user is allowed.

This overload is used when silent_or_group is of type ScriptGroup.

Parameters:
group (ScriptGroup) – The group.

Return type:
bool

Returns:
True if the permission is allowed.

get_permission_state(group, resolve_effective=True, resolve_inherited=False)
Gets the the state of a specific permission.

You can use System.commands to search for a command guid.

Parameters:
group (ScriptGroup) – The group.

resolve_effective (bool) – If True, when the permission is not explicitely granted or denied, it will be resolved (e.g. by asking the parent object, and finally deferring to a default value). This value overrides resolve_inherited.

resolve_inherited (bool) – If set to True, for hierarchical properties (currently only the object access properties), the parent objects are resolved for inherited properties. If set to false, only the properties directly set at the object are resolved. If resolve_effective is True, the parents are always resolved and this parameter is ignored.

Return type:
PermissionState

Returns:
If resolve_effective is True, PermissionState.Granted or PermissionState.Denied. If resolve_effective is False, PermissionState.Default might be returned additionally.

set_permission_state(group, state)
Sets the permissions for a specific command.

Parameters:
group (ScriptGroup) – The group.

state (PermissionState) – The state.

check_set_permission_state(group, state, silent=True)
Checks whether our group is allowed to set a specific permission.

Parameters:
group (ScriptGroup) – The group.

state (PermissionState) – The state.

silent (bool) – If False, when the permission is not granted, the RequestAuthorization event is triggered which typically prompts a new login interactively and the permission is checked again with the new login. If True, nothing will be prompted.

Return type:
bool

Returns:
True if the user is allowed.

classScriptUserManagement.ScriptObjectPermission
Bases: ScriptPermission

ObjectAccess Permissions come with additional information about which object to access, and the specific kind of object access.

check_permission_extended()
Checks the effective permission the current user has for the given object.

This considers permission inheritance along the object tree etc. This method may prompt the user for a new login.

Return type:
Exception

Returns:
An Exception object describing why the user currently does not have access for the given object, and None if the user has access.

propertytarget_object
Target object.

Return type:
ScriptObject

 propertyaccess_kind
Access kind.

Return type:
ObjectPermissionKind

classScriptUserManagement.ScriptCommandPermission
Bases: ScriptPermission

Permissions for commands come with the command guid.

propertycommand_guid
Gets the command guid.

Return type:
Guid

classScriptUserManagement.ScriptFactoryPermission
Bases: ScriptPermission

Permissions for factories come with a guid describing the object factory.

propertyfactory_guid
Gets the factory guid.

Return type:
Guid

ScriptDeviceObject
classScriptDeviceObject.DeviceTrackingMode(value)
Bases: Enum

Enumeration that defines how a device is tracked on the network.

Name= 0
Tracked by name (e.g. ‘MyPlc’).

SystemAddress= 1
Tracked by system address (e.g. ‘[056D]’).

IPAddressUdp= 2
Tracked by IP using UDP broadcasts.

IPAddressTcp= 3
Tracked by IP using TCP point-to-point connection.

Gateway= 4
Device is a Gateway and will not be tracked.

Dummy= 5
Placeholder device will not be tracked.

DNS= 6
Tracked by Dns-Address using TCP point-to-point connection.

classScriptDeviceObject.StopResetBehaviour(value)
Bases: Enum

An enumeration.

KeepCurrentValues= 0
The outputs keep the last current values.

SetToDefault= 1
The outputs are set to the default values.

ExecuteProgram= 2
A user defined program is executed.

classScriptDeviceObject.ConnectorRole(value)
Bases: Enum

Describes the role of a connector

Parent= 0
The connector allows other devices to be connected to the connectors device.

Child= 1
The connector allows its device to be connected to another device.

classScriptDeviceObject.AccessRight(value)
Bases: Enum

Defines access rights on a parameter.

None= (0,)
The element is not accessible.

Read= 1
Specifies that the element may be read.

Write= 2
Specifies that it is allowed to write to the element.

ReadWrite= 3
Combination of read and write access: The element may be written and read.

classScriptDeviceObject.ChannelType(value)
Bases: Enum

Defines the types of a channel.

None= 0
Not a channel.

Input= 1
An input channel.

Output= 2
An output channel.

OutputReadOnly= 3
A readonly output channel.

classScriptDeviceObject.DiagType(value)
Bases: Enum

Describes the function of a parameter in respect to module diagnosis.

None= (0,)
No diagnostic meaning

Diagnosis= (1,)
Provides the diagnostic message

Acknowledge= 2
Acknowledge for current diagnostic message

classScriptDeviceObject.ScriptDeviceObjectMarker
Bases: object

Every ScriptObject instance will be extended with this method.

propertyis_device
Gets a value indicating whether this instance is a device object.

Return type:
bool

classScriptDeviceObject.ScriptDeviceObject
Bases: ScriptDeviceObjectMarker

Functionality for manipulating device objects.

All device objects implementing DeviceObject will be extended with this methods.

get_device_identification()
Gets the device identification.

Return type:
DeviceId

enable()
Marks this device as enabled during download.

disable()
Marks this device as disabled during download.

is_enabled()
Determines whether this instance is enabled during download.

Return type:
bool

Returns:
True if this instance is enabled during download; otherwise, False.

update(type: int, id: str, version: str, module: Optional[str] = None)
Updates the specified device.

Parameters:
type (int) – The device type.

id (str) – The device identification.

version (str) – The device version.

module (str) – The module ID. (This parameter is optional.)

plug(name: str, type: int, id: str, version: str, module: Optional[str] = None)
Plugs the specified device.

Parameters:
name (str) – Name of the device.

type (int) – The device type.

id (str) – The device identification.

version (str) – The device version.

module (str) – The module ID. (This parameter is optional.)

add(name: str, type: int, id: str, version: str, module: Optional[str] = None)
Adds the specified device.

Parameters:
name (str) – Name of the device.

type (int) – The device type.

id (str) – The device identification.

version (str) – The device version.

module (str) – The module ID. (This parameter is optional.)

insert(name: str, index: int, type: int, id: str, version: str, module: Optional[str] = None)
Inserts the specified device at the specified index.

Parameters:
name (str) – Name of the device.

index (int) – Index where to insert the device.

type (int) – The device type.

id (str) – The device identification.

version (str) – The device version.

module (str) – The module ID. (This parameter is optional.)

unplug()
Unplugs the specified device.

get_simulation_mode()
Gets the simulation mode.

Returns:
True if simulation is enabled.

set_simulation_mode(simulation)
Sets the simulation mode.

Parameters:
simulation (bool) – if set to True, simulation is enabled.

get_gateway()
Gets the gateway.

See also: ScriptDeviceObject.get_device_communication_settings

Return type:
Guid

Returns:
The guid of the gateway.

get_address()
Gets the address of the device.

See also: ScriptDeviceObject.get_device_communication_settings

Return type:
str

Returns:
The device address in the bus independent CODESYS format.

set_gateway_and_address(gateway: ScriptGateway, address: str)
Sets the gateway and address.

If you pass the empty gateway and an empty address, the gateway address will be cleared. You can use ScriptGateway.find_address_by_ip() to search the CODESYS address when you know the ip address or hostname.

Parameters:
gateway (ScriptGateway) – The gateway.

address (str) – The address in the bus independent CODESYS format.

get_module_identification()
Returns the unique identification of a module.

A module is a special type of device, that is only available within the context of a certain device. The module is identified by the same values as each owning device, with an additional module id, to distinguish it from other modules of the same device.

Examples for modules are device local io modules and similar nodes.

Version added:
3.4.4.0

Return type:
str

Returns:
The module identification, or an empty string if this module has no module identification.

allow_interfaces_at(index)
Get the name of the child interfaces that this device object can accept at the specified insert position.

Version added:
3.5.4.0

Parameters:
index (int) – The child index where a device should be inserted.

Return type:
list[str]

Returns:
A list of possible interface names or None if no device can be inserted at that position.

propertydevice_parameters
Gets the set of device parameters.

Since V3.5.8.0, this actually is a ScriptMappableDeviceParameterSet.

Version added:
3.5.4.0

Return type:
ScriptDeviceParameterSet

 propertyconnectors
Gets the connectors.

Return type:
ScriptDeviceConnectorSet

set_gateway_and_device_name(gateway: str, device_name: str)
Sets the gateway and device name for communication.

If you pass the empty guid and an empty address, the gateway address will be cleared. The device will be tracked by its device name - when trying to go online, a quick online scan will be made and the first device with the given name will be selected.

Version added:
3.5.8.0

Parameters:
gateway (str) – The gateway Guid(as string) or its name.

device_name (str) – The device name.

set_gateway_and_ip_address(gateway: str, ip_address: IPAddress, port: int = 11740)
Sets the gateway and IP address for communication.

Version added:
3.5.8.0

Parameters:
gateway (str) – The gateway guid (as string) or name.

ip_address (IPAddress) – The IP Address.

port (ushort) – The port. Omit to use the default port 11740.

Raises:
InvalidOperaionException – If gateway is passed as a string and several gateways have the same name.

get_device_communication_settings()
Gets the communication settings of the device.

Return type:
ScriptCommunicationSettings

export_io_mappings_as_csv(file_path)
Export the io mappings as a CSV file to the specified absolute path.

Version added:
3.5.8.0

Parameters:
file_path (str) – The absolute path of the file to export.

import_io_mappings_from_csv(file_path)
Imports the io mappings from a CSV file at the specified absolute path.

Version added:
3.5.8.0

Parameters:
file_path (str) – The absolute path of the file to import.

propertydriver_info
Get the driver info of the device.

Version added:
3.5.9.0

Return type:
ScriptDriverInfo

 propertyallow_symbolic_var_access_in_sync_with_iec_cycle
Property used by the symbol configuration to determine if symbolic variable access is allowed to be synchronized with the IEC cycle.

The default is False and should be kept for most use cases. Setting this to True may increase the jitter for all applications running on the device because the task accessing the variables may block other tasks. The device object has to support DeviceObject (3.5.10.0) to access the value.

Version added:
3.5.10.0

Return type:
bool

classScriptDeviceObject.ScriptProjectDeviceExtension
Bases: object

Functionality to add top-level devices (e. G. SPS) to projects.

ScriptProject instances are amended with these objects.

Version added:
3.4.3.0

add(name: str, type: int, id: str, version: str, module: Optional[str] = None)
Adds the specified device.

Parameters:
name (str) – Name of the device.

type (int) – The device type.

id (str) – The device identification.

version (str) – The device version.

module (str) – The module ID. (This parameter is optional.)

classScriptDeviceObject.DeviceId
Bases: object

Represents a Device ID.

An implementation class of this interface is injected under the name “DeviceID” into the python scope, so python code can create device IDs without the need to subclass that interface. The constructor signature is: DeviceID(int iType, string stId, string stVersion)

propertytype
Type of the device.

Return type:
int

 propertyid
Id of the device.

The format for this id is specified for each type. The id is unique within the class of devices of one type.

Return type:
str

 propertyversion
The version of the device.

The format for the version string is specified for each type.

Return type:
str

classScriptDeviceObject.ModuleId
Bases: DeviceId

Unique identification for a module.

A module is a special type of device, that is only available within the context of a certain device. The module is identified by the same values as each owning device, with an additional module id, to distinguish it from other modules of the same device.

Examples for modules are device local io modules and similar nodes.

propertymodule_id
Id of the module.

The format for this id is specified for each type. The id is unique within the class of devices of one type.

Return type:
str

classScriptDeviceObject.ScriptCommunicationSettings
Bases: object

Provides access to the communication settings of the device.

propertygateway_guid
The guid of the gateway.

Return type:
Guid

 propertydevice_address
The address of the device.

Return type:
str

 propertyprompt_at_login
Whether there’s a prompt at login.

Return type:
bool

 propertysecure_online_mode
Gets a boolean value indicating whether secure online mode is activated for the corresponding devices.

If set, user interfaces should prompt the user before an operation is executed which changes the state of the controller.

Return type:
bool

 propertydevice_name
Gets the name of the device as entered on the communication settings page.

Return type:
str

 propertymonitoring_interval_msec
The interval for status and variable monitoring measured in milliseconds.

Default = 200ms, Minimum = 10ms, Maximum = 1000ms, Increment 10ms. Invalid values will be ignored

Return type:
int

 propertymonitoring_interval
The interval for status and variable monitoring measured in milliseconds.

Default = 200ms, Minimum = 10ms, Maximum = 1000ms, Increment 10ms. Invalid values will be ignored

Return type:
TimeSpan

 propertyTrackingMode
Property to get the mode used to track a device on the network - whether the device is tracked via CODESYS address, ip address or name.

Return type:
DeviceTrackingMode

 propertyscanned_device_name
The name of the physical device (E.g. “MyPlc”), as seen in the network scan.

Return type:
str

 propertyscanned_ip_address_and_port
Device IP Address and Port if block driver TCP is used for connection.

Format: “192.168.101.109:11740”, as seen in the network scan.

This may return the emtpy string if it’s not available. Even if some network scan members are set, this does not guarantee that all of them are set.

Return type:
str

 propertyscanned_target_id
Target ID.

Format: “1234 ABCD” (=hexadecimal), same as in device description, as seen in the network scan.

This may return the emtpy string if it’s not available. Even if some network scan members are set, this does not guarantee that all of them are set.

Return type:
str

 propertyscanned_target_name
The name of the target (E.g. “CODESYS PLC Win NT”), as seen in the network scan.

This may return the emtpy string if it’s not available. Even if some network scan members are set, this does not guarantee that all of them are set.

Return type:
str

 propertyscanned_target_type
Target Type (Format: “4096” (=decimal), same as in device description), as seen in the network scan.

This may return the emtpy string if it’s not available. Even if some network scan members are set, this does not guarantee that all of them are set.

Return type:
str

 propertyscanned_target_vendor
The vendor of the target, as seen in the network scan.

This may return the emtpy string if it’s not available. Even if some network scan members are set, this does not guarantee that all of them are set.

Return type:
str

 propertyscanned_target_version
The version of the target, as seen in the network scan.

This may return the emtpy string if it’s not available. Even if some network scan members are set, this does not guarantee that all of them are set.

Return type:
str

 propertyis_communication_encrypted
Get or set if encrypted communication should be used with the device.

Version added:
3.5.16.10

Return type:
bool


ScriptSystem
classScriptSystem.PromptHandling(value)
Bases: Enum

This enum is obsolete. Use ScriptPromptHandling, System.script_prompt_handling, System.process_script_prompts and System.log_prompt_details instead. For textual prompts in noUI mode please use the command line switch ‘–textPrompts’.

NONE= 0
Use ScriptPromptHandling.SuppressPrompts instead.

ForwardSimplePrompts= 1
Use ScriptPromptHandling.ForwardUnknownPrompts instead.

LogSimplePrompts= 2
Use ScriptPromptHandling.LogPrompts instead.

EnableTextPrompts= 4
Use the command line switch ‘–textPrompts’ instead.

ProcessScriptPrompts= 8
Use System.process_script_prompts instead.

LogMessageKeys= 16
Use System.log_prompt_details instead.

classScriptSystem.ScriptPromptHandling(value)
Bases: Enum

Definition flags for prompt handling via scripting. Prompts are standard dialog boxes issued by plugins to inform or query the user.

For all prompts with a message key a specific handling can be deposited in System.prompt_answers. This enum may be extended in future releases. Currently, all handling choices are cumulative, but some flags have priority e.g. if a prompt is forwared LogPrompts has no effect. This enum replaces PromptHandling. Textual prompts in noUI mode are no longer supported via scripting. If textual prompts are required, please use the command line switch ‘–textPrompts’.

SuppressPrompts= 0
None of the flags are set. This implies that prompts are silently suppressed using their default selction and result. If no default selection can be applied, an exception is thrown.

LogPrompts= 1
Logs handled prompts. This includes the message, the prompt result and the options that were set. This flag has no effect, if the prompt was forwarded.

ForwardUnknownPrompts= 2
If this flag is set, prompts are answered according to specified handling in System.prompt_answers. If no handling was deposited for the prompt or the prompt has no message key, it is always forwarded.

AlwaysForwardPrompts= 4
All prompts are forwarded to the underlying message service. Usually this is the message service of the automation platform, which means in UI mode prompts are shown as popup or in noUI mode as text in the CLI. But it is explicitly not guaranteed which is the underlying message service.

classScriptSystem.Severity(value)
Bases: Enum

Describes the severity of an _3S.CoDeSys.Core.Messages.IMessage.

FatalError= (1,)
Indicates that the corresponding message is a fatal error.

Error= (2,)
Indicates that the corresponding message is an error.

Warning= (4,)
Indicates that the corresponding message is a warning.

Information= (8,)
Indicates that the corresponding message is an information.

Text= 16
Indicates that the corresponding message is an informational text without corresponding source code position.

classScriptSystem.PromptChoice(value)
Bases: Enum

This enumeration denotes possible prompt options for _3S.CoDeSys.Core.IMessageService methods.

OK= (0,)
The user can choose “OK”.

OKCancel= (1,)
The user can choose “OK” or “Cancel”.

YesNo= (2,)
The user can choose “Yes” and “No”.

YesNoCancel= (3,)
The user can choose “Yes”, “No”, and “Cancel”.

RetryCancel= (4,)
The user can choose “Retry” or “Cancel”.

AbortRetryIgnore= 5
The user can choose “Abort”, “Retry”, and “Ignore”.

classScriptSystem.PromptResult(value)
Bases: Enum

This enumeration denotes possible prompt results from _3S.CoDeSys.Core.IMessageService methods.

OK= (0,)
The user has selected “OK”.

Cancel= (1,)
The user has selected “Cancel”.

Yes= (2,)
The user has selected “Yes”.

No= (3,)
The user has selected “No”.

Retry= (4,)
The user has selected “Retry”.

Abort= (5,)
The user has selected “Abort”.

Ignore= 6
The user has selected “Ignored”.

classScriptSystem.System
Bases: object

Access to generic CoDeSys system functionality.

An instance of this object is planted into the scriptengine module with the name “system”.

exit(exitcode=0)
Exits the application platform by shutting down the engine and exiting the process.

If you just want to terminate the script execution without exitting the platform, call sys.exit() or raise a SystemExitException. (When running the script via –runscript command line parameter in –noUI-Mode, this will also terminate CoDeSys, as there’s nothing else to do after the script exitted.)

Parameters:
exitcode (int or None) – The exitcode we return to the operating system. If omitted, we return the ExitCode 0 which normally means success.

propertytrace
Gets or sets a value indicating whether trace System is active on the current script execution.

trace is the replacement for the old “echo” functionality in the CoDeSys V2.3 batch mode. It adds log messages (Category ScriptMessage, Severity Info) into the IMessageStorage on the following events: Change of source code line, entering and exitting of python scope, exception thrown in python code.

This setting may be ignored: For example, due to internal restrictions in the IronPython Engine, script tracing is disabled in debugging mode.

Return type:
bool

Returns:
True if trace is activated; otherwise, False.

 propertyui_present
Gets a value indicating whether we have an UI.

If this is false, we’re running in a console application or background service.

Return type:
bool

Returns:
True if [UI present]; otherwise, False.

write_message(severity, stMessage, obj=None, position=-1, length=None)
Writes the message to the Message Store.

Position and length are only meaningfull if obj is a ScriptObject and are ignored otherwise.

Parameters:
severity (Severity) – The severity.

stMessage (str) – The message.

obj (ScriptTreeObject) – The ScriptObject or ScriptProject the message belongs to.

position (long) – The position including offset in the data for the message.

length (int) – The length in the data for the message.

get_messages(category='{194B48A9-AB51-43ae-B9A9-51D3EDAADDF3}')
Gets all messages of a given category which are currently in the store.

Parameters:
category (str) – The category Guid (defaults to the ScriptMessage category)

Return type:
list

Returns:
The list of message texts

propertyprompt_answers
Gets the prompt answers Dictionary for simulating interactive user input.

This dictionary is used to intercept the IMessageService interface. It only applies, if ScriptPromptHandling.AlwaysForwardPrompts is not set. Whenever a method with a message_key is called, the dictionary is searched for the message_key. If found, the corresponding value is returned.

For this to work, all the keys must be strings matching the message_key values. For Prompts, the following possibilities exist:

A PromptResult member

One of the PromptResult enum members, the list is PromptResult.OK, PromptResult.Cancel, PromptResult.Yes,:attr:PromptResult.No, PromptResult.Retry,:attr:PromptResult.Abort and PromptResult.Ignore. It depends on the exact prompt command which values make sense.

An int

The MultipleChoicePrompt methods will try to convert the value to an integer for the choice which was selected.

A MultipleChoiceSelector delegate

For the MultipleChoicePrompt methods, you can also give a delegate which gets the list of strings and returns the result.

A tuple <PromptResult member, PromptChoiceFilter delegate>

Some prompts present a list with possibly multiple selectable choices, and return a PromptResult. For those prompts, a PromptResult is accepted as value (with results in none of the choices being selected), or a Tuple <list> containing at least 2 elements: a PromptResult followed by a PromptChoiceFilter delegate which allows the script for fine grained selection.

A tuple <PromptResult member, PromptCustomControlValueProvider delegate>

Some prompts contain a custom control (e.g. with textboxes or dropdowns) and return a Prompt Result. For those prompts, a Tuple <list> containing at least 2 elements: a PromptResult followed by a PromptCustomControlValueProvider delegate which allows the script for fine grained selection.

If the value given does not make sense in the context of the current prompt, an InvalidCastException is raised.

For errors, the values are not used and don’t matter (may be None / None).

To give best semantics for the scripts, this dictionary is a PythonDictionary instance, that means you can easily add values:

# set a value:
System.prompt_answers["OverWriteFiles"] = PromptResult.Cancel

# Set multiple values:
System.prompt_answers.update(
   {"OverWriteFiles": PromptResult.OK,
    "DisFullError": None})

# Reset everything:
System.prompt_answers.clear()
Return type:
dict

Returns:
The prompt answers.

 propertyexecutable_filename
Gets the name of the executable file (the currently running application).

Return type:
str

process_messageloop()
Processes the Win32 message loop of the current Thread, if present.

This allows the UI to be updated during long running processes. It should be safe to call this from python scripts without reentrancy problems, because the ScriptExecutor calls SystemInstances.Engine.Frame.StartLengthyOperation(); to prevent the user from triggering more commands while the script is running.

delay(milliseconds)
Delays the script for the specified amount of milliseconds.

The message loop is served during the wait to allow background tasks to be processed. The actual duration of the delay will not meet hard realtime requirements.

Parameters:
milliseconds (int) – The duration to wait

propertyprompt_handling
Gets or sets the way message service prompts are handled.

Version added:
3.5.1.0

Return type:
PromptHandling

 propertyui
Gets the script ui instance.

Version added:
3.5.1.0

Return type:
ScriptUI

 propertycommands
Gets the commands.

Version added:
3.5.1.0

Return type:
ScriptCommands

 propertyfactories
Gets the factories.

Version added:
3.5.1.0

Return type:
ScriptObjectFactories

execute_on_primary_thread(code, async=False)
Executes a specified piece of code in the primary thread.

!!Experts Only!!

Advanced users only! Using multiple threads is neither officially supported nor encouraged in CoDeSys python scripts, you do that “on your own risk”. This method is safe to be called from non-primary threads. This method relies on the primary thread processes its message queue. (If you don’t know what the message queue is, threads are probably not the right thing for you…) Be careful to ensure that all your own threads are finished when the main thread exits the script, or strange effects can occur. You can use the .NET System.Threading or the python threading module to create new threads.

Version added:
3.5.1.0

Parameters:
code (PieceOfCode) – The code to execute. A python function, which will be called without parameters, and should not return any value.

async (bool) – If true, this method returns immediately, otherwise the this method returns after the delegate has been finished.

get_message_objects(category=None, severities=4294967295)
Gets all messages of a given category and severity which are currently in the store.

Version added:
3.5.2.0

Parameters:
category (Guid or str) – The category Guid (defaults to the ScriptMessage category).

severities (Severity) – The severities (This can be a combination of several severity flags). By default, all severities are returned.

Return type:
list

Returns:
The list of message texts.

get_message_categories(bActive=True)
Gets all message categories.

Version added:
3.5.2.0

Parameters:
bActive (bool) – If set to True (the default), only the active ones (those which had at least one message since the current codesys instance was started) are returned. If set to false, all categories existing in the current installation are returned.

Return type:
list[Guid]

Returns:
A list of guids.

get_message_category_description(category)
Gets a description for the specified message category.

Version added:
3.5.2.0

Parameters:
category (Guid) – The category.

Return type:
str

Returns:
The description of that message category.

clear_messages(category)
Clears the specified category.

Version added:
3.5.2.0

propertyabortable
Whether the script is abortable.

Since V3.5.5.0, scripts are abortable by default. The user can abort the script by pressing the Cancel button in the progress display. This property controls whether this Cancel button is enabled.

Version added:
3.5.5.0

Return type:
bool

 propertyabort_autocheck
Gets or sets a value indicating whether this script execution automatically checks for aborts.

If this property is set to True (the default value), the script engine uses the python tracing functionality to check for aborts after every line of executed python code, and throws an KeyboardInterruptException if aborted. You can disable this automatic checks by setting this property to false. Certain debuggin modes also disable this check.

Version added:
3.5.5.0

Return type:
bool

 propertyaborting
Gets a value indicating whether this System is aborting.

This property gets set to true once the user presses an enabled “Cancel” button on the progress display, and it cannot be reset by the script. Use this property for explicit abortion checks when you disabled abort_autocheck.

Version added:
3.5.5.0

Return type:
bool

progress_start(description, items=-1, unit='')
Starts the progress information for a specific subtask.

Version added:
3.5.5.0

Parameters:
description (str) – The description of the subtask.

items (int) – The number of items, if known in advance.

unit (str) – The unit of items, for example objects or lines.

progress_step(item, completed=1)
Advances the progress of the current subtask.

Version added:
3.5.5.0

Parameters:
item (str) – The item which is currently completed.

completed (int) – The number of items completed in this step.

progress_absolute(item, absolute_progress)
Advances the progress of the current subtask.

Version added:
3.5.5.0

Parameters:
item (str) – The item which is currently completed.

absolute_progress (int) – The total number of items completed so far.

propertybackground_loading_of_libraries_finished
Is the background loading of libraries finished?

Version added:
3.5.15.0

Return type:
bool

 propertyscript_prompt_handling
Defines how prompts are handled. For textual prompts in noUI mode use the command line switch ‘–textPrompts’.

Version added:
4.2.0.0

Return type:
ScriptPromptHandling

 propertyprocess_script_prompts
If set, prompts issued by the script itself via System.ui are also subject to the ISystem6.script_prompt_handling and System.prompt_answers processing / filtering.

Version added:
4.2.0.0

Return type:
bool

 propertylog_prompt_details
Logs details for all message service calls to the message store. Use this to catch the message keys, options, choices and PromptChoice you need for System.prompt_answers.

The details are logged as a json string.

Version added:
4.2.0.0

Return type:
bool

classScriptSystem.ScriptMessage
Bases: object

Represents a message from the message storage.

propertyproject
The the project of the message position.

If this message does not have a position, None is returned.

Return type:
ScriptProject

 propertyobject
The object of the message position.

If this message does not have a position, None is returned.

Return type:
ScriptObject

 propertyposition
The position within the database object of the message position.

The interpretation of this number is handled privately by the object. To get a user-friendly display text for this position, the position_text property must be called. If this message does not have a position, 0 is returned.

Return type:
long

 propertyposition_text
The user-friendly display text for position within the database object of the message position.

The interpretation of this number is handled privately by the object. If this message does not have a position, None is returned.

Return type:
str

 propertyposition_offset
Gets an additional character offset to the position returned by the position property.

Return type:
short

 propertylength
Gets length of Position.

Return type:
int

 propertytext
Gets the message text.

Return type:
str

 propertyseverity
Gets the severity of this message.

Return type:
Severity

 propertyFontColor
Gets the color of the message text, or System.Drawing.Color.Empty if the default color is defined.

Return type:
Color

 propertyhas_details_handler
Gets a value indicating whether this ScriptMessage has a details handler.

This is visually indicated by a […]-Button in the message view.

Return type:
bool

call_details_handler()
Calls the details handler of this message (this will usually open a popup or similar).

propertyicon
Specialized Icon. If None, the icon is set according to the severity.

Return type:
Icon

 propertynumber
Unambigous number identifying the message according to its category.

Together with the prefix, the number identifies the message. compile, LINT, IO-Config, etc. None is returned if not used.

Return type:
int or None

 propertyprefix
A prefix string identifying the message category (compile, LINT, IO-Config, etc).

Together with the number, the message is unambigously identified. None is returned if not used.

Return type:
str

ScriptSystem.PieceOfCode(self)
Delegate for a parameterless function without return value.

classScriptSystem.ScriptUI
Bases: object

The script can interact with the user via this instance.

Please note that some of the functionalities depend on the currently installed MessageService instance.

In –noUI-Mode (console-only mode), a basic, somehow restricted implementation querying the user via text input is provided instead. Especially multi-line input is not user friendly, and store_key or predefined values for text input do not work. But as –noUI-Mode is primarily meant for unattended batch execution, it is a bad idea to ask the user in general.

error(message, message_key='ScriptMessage', arguments=None)
Reports an error message to the user. This method blocks until the user has acknowledged this message.

Parameters:
message (str) – The message to display the user.

message_key (str) – The message key, for automated filtering / handling by prompt_answers or similar mechanism by other plugins (e. G. automated test tools). Most users can leave the default here.

arguments (tuple[object]) – Optional objects which build the variable part of the message. In other words, if message is build via a string formatting operation, the arguments of that formatting operation should be passed as arguments here. This is for advanced usages via automated test tools, most users can ignore it.

warning(message, message_key='ScriptMessage', arguments=None)
Reports an warning message to the user.

This method blocks until the user has acknowledged this message.

Parameters:
message (str) – The message to display the user.

message_key (str) – The message key, for automated filtering / handling by prompt_answers or similar mechanism by other plugins (e. G. automated test tools). Most users can leave the default here.

arguments (tuple[object]) – Optional objects which build the variable part of the message. In other words, if message is build via a string formatting operation, the arguments of that formatting operation should be passed as arguments here. This is for advanced usages via automated test tools, most users can ignore it.

info(message, message_key='ScriptMessage', arguments=None)
Reports an informational message to the user.

This method blocks until the user has acknowledged this message.

Parameters:
message (str) – The message to display the user.

message_key (str) – The message key, for automated filtering / handling by prompt_answers or similar mechanism by other plugins (e. G. automated test tools). Most users can leave the default here.

arguments (tuple[object]) – Optional objects which build the variable part of the message. In other words, if message is build via a string formatting operation, the arguments of that formatting operation should be passed as arguments here. This is for advanced usages via automated test tools, most users can ignore it.

prompt(message, choice, default_result, store_description=None, store_key=None, message_key='ScriptMessage', arguments=None)
Prompts the user.

This method blocks until the user has answered the question.

This method allows the user to store his/her answer. The next time the same question is prompted to the user by this method, the method immediately returns with the stored result. See also: reset_stored_result()

Parameters:
message (str) – The message to display.

choice (PromptChoice) – The answers the user can chose from.

default_result (PromptResult) – The default answer which is displayed to the user in a highlighted manner.

store_description (str) – The text which is displayed next to the control where the user can decide that (s)he does not want to see that question again (e.g. “Do not show this message again”, or “Apply for all objects”). This is optional, but you must supply either both store_description and store_key or none of them.

store_key (str) – A non-None caller-specific key with which the prompt can be identified. This is optional, but you must supply either both store_description and store_key or none of them.

message_key (str) – The message key, for automated filtering / handling by System.prompt_answers or similar mechanism by other plugins (e. G. automated test tools). Most users can leave the default here.

arguments (str) – Optional objects which build the variable part of the message. In other words, if message is build via a string formatting operation, the arguments of that formatting operation should be passed as arguments here. This is for advanced usages via automated test tools, most users can ignore it.

Return type:
PromptResult

Returns:
The answer provided by the user.

select_many(message, choice, result, items, message_key='ScriptMessage', *arguments)
Prompts the user, allowing the user to select items for which to apply the answer.

This method blocks until the user has answered the question.

This method allows the user to store his/her answer. The next time the same question is prompted to the user by this method, the method immediately returns with the stored result.

Parameters:
message (str) – The message to display.

choice (PromptChoice) – The answers the user can chose from.

result (PromptResult) – The result.

items (list) – An array containing items which are selectable for the user. The objects’ ToString methods are used to get the string to display.

message_key (str) – The message key, for automated filtering / handling by System.prompt_answers or similar mechanism by other plugins (e. G. automated test tools). Most users can leave the default here.

arguments (str) – Optional objects which build the variable part of the message. In other words, if message is build via a string formatting operation, the arguments of that formatting operation should be passed as arguments here. This is for advanced usages via automated test tools, most users can ignore it.

Return type:
list

Returns:
A python tuple containing of the PromptResult as the first item, list of booleans in parallel to``items`` as second item, and a (possibly empty) sequence of the selected objects as third item.

choose(message, options, initial_selection=0, cancellable=True, message_key='ScriptMessage', *arguments)
Lets the user choose one of several listed items.

Parameters:
message (str) – The message to display.

options (list) – A list of options to display. The objects will be converted to string to show them to the user.

initial_selection (int) – The index of the initially selected object of the list.

cancellable (bool) – if set to true, the user can cancel / abort the dialog.

message_key (str) – The message key, for automated filtering / handling by System.prompt_answers or similar mechanism by other plugins (e. G. automated test tools). Most users can leave the default here.

arguments (str) – Optional objects which build the variable part of the message. In other words, if message is build via a string formatting operation, the arguments of that formatting operation should be passed as arguments here. This is for advanced usages via automated test tools, most users can ignore it.

Return type:
list

Returns:
A python tuple containing the index of the selected item, or -1 if cancellable was set to True and the user cancelled the dialog as the first item, and the selected item or None as the second item.

reset_stored_result(store_key)
Resets any prompt results stored by prompt() or select_many().

Parameters:
store_key (str) – A non-None caller-specific key with which the prompt can be identified.

open_file_dialog(title=None, filename=None, directory=None, filter=None, filter_index=None, default_extension=None, stateguid=None, multiselect=False, check_file_exists=True, check_path_exists=True)
Displays an “Open File” dialog.

This method is currently not processed by System.prompt_answers.

In –NoUI-Mode, the user simply can enter a path here.

The “filter” string is a list of descriptions and pattern lists, separated by a pipe symbol (‘|’). The pattern list uses the glob syntax, and is separated by a semicolon (‘;’). For example: Text files (*.txt)|*.txt|Image Files(*.BMP;*.JPG;*.GIF)|*.BMP;*.JPG;*.GIF|All files (*.*)|*.*

Parameters:
title (str) – The title of the dialog window, if you don’t pass it, a generic “Python Script: Open File” like text will be displayed.

filename (str) – The initially selected filename.

directory (str) – The directory initially displayed. Default is None, which uses the current directory.

filter (str) – The list of valid extension filters.

filter_index (str) – Index of the filter which is active when the user opens the dialog. This index is 1-based.

default_extension (str) – The default extension which is added to the filename if the user does not add an extension, and the active filter does not specify one.

stateguid (Guid) – This GUID is used to store the state inside the CoDeSys configuration space when the user closes the Dialog with “ok”, and will be used to restore the state when the next dialog is opened with the same guid.

multiselect (bool) – if set to True, the user may select multiple files.

check_file_exists (bool) – if set to True, the dialog displays a warning if the user enters a file which does not exist.

check_path_exists (bool) – if set to True, the dialog displays a warning if the user enters a path which does not exist.

Return type:
obj

Returns:
The path for the selected file, or a list of pathes if multiselect is allowed, or None if the user cancelled the dialog.

save_file_dialog(title=None, filename=None, directory=None, filter=None, filter_index=None, default_extension=None, stateguid=None, check_file_exists=True, check_path_exists=True, check_overwrite=True, check_create=False)
Displays a “Save File” dialog.

This method is currently not processed by System.prompt_answers.

In –NoUI-Mode, the user simply can enter a path here.

The “filter” string is a list of descriptions and pattern lists, separated by a pipe symbol (‘|’). The pattern list uses the glob syntax, and is separated by a semicolon (‘;’). For example: Text files (*.txt)|*.txt|Image Files(*.BMP;*.JPG;*.GIF)|*.BMP;*.JPG;*.GIF|All files (*.*)|*.*

Parameters:
title (str) – The title of the dialog window, if you don’t pass it, a generic “Python Script: Save File” like text will be displayed.

filename (str) – The initially selected filename.

directory (str) – The directory initially displayed. Default is None, which uses the current directory.

filter (str) – The list of valid extension filters.

filter_index (str) – Index of the filter which is active when the user opens the dialog. This index is 1-based.

default_extension (str) – The default extension which is added to the filename if the user does not add an extension, and the active filter does not specify one.

stateguid (Guid) – This GUID is used to store the state inside the CoDeSys configuration space when the user closes the Dialog with “ok”, and will be used to restore the state when the next dialog is opened with the same guid.

check_file_exists (bool) – if set to True, the dialog displays a warning if the user enters a file which does not exist.

check_path_exists (bool) – if set to True, the dialog displays a warning if the user enters a path which does not exist.

check_overwrite (bool) – if set to True, the dialog displays a warning if the user selection will overwrite an existing file.

check_create (bool) – if set to True [check_create].

Return type:
str

Returns:
The path for the selected file, or None if the user cancelled the dialog.

browse_directory_dialog(message, path='', root_folder='Environment.SpecialFolder.MyComputer', new_folder_button=True)
Opens a browse directory dialog.

This method is currently not processed by System.prompt_answers.

In –NoUI-Mode, the user simply can enter a path here.

The microsoft documentation for the root folder says: “Only the specified folder and any subfolders that are beneath it will appear in the dialog box and be selectable. The SelectedPath property, along with RootFolder, determines what the selected folder will be when the dialog box is displayed, as long as SelectedPath is an absolute path that is a subfolder of RootFolder (or more accurately, points to a subfolder of the shell namespace represented by RootFolder).”

Parameters:
message (str) – The message to display.

path (str) – The path to be preselected when the dialog opens.

root_folder (Environment.SpecialFolder) – The root folder for the browsing dialog.

new_folder_button (bool) – if set to True, a button which allows the users to create new folders appears in the dialog box.

Return type:
str

Returns:
The path for the selected directory, or None if the user cancelled the dialog.

query_string(message='', text='', multi_line=False, cancellable=False)
Queries the user to input or edit a text string.

This method is currently not processed by System.prompt_answers.

Parameters:
message (str) – The message to display for the user.

text (str) – The text to be prefilled in the textbox.

multi_line (bool) – if set to True, the user can enter a multiline text.

cancellable (bool) – if set to True, the user can cancel / abort the dialog.

Return type:
str

Returns:
The entered string, or None if the user cancelled the dialog.

query_password(message='', password='', cancellable=False)
Queries the user to input a password.

This method is currently not processed by System.prompt_answers.

Parameters:
message (str) – The message to display for the user.

password (str) – The password to be prefilled in the textbox.

cancellable (bool) – if set to True, the user can cancel / abort the dialog.

Return type:
str

Returns:
The entered password, or None if the user cancelled the dialog.

query_credentials(message='', username='', password='', cancellable=False)
Queries the user to input a password.

This method is currently not processed by System.prompt_answers.

Parameters:
message (str) – The message to display for the user.

username (str) – The username to be prefilled in the textbox.

password (str) – The password to be prefilled in the textbox.

cancellable (bool) – if set to True, the user can cancel / abort the dialog.

Return type:
list

Returns:
A tuple containing the username and password, or None if the user did cancel the dialog.

ScriptSystem.MultipleChoiceSelector(self, choices)
Delegate for selecting one of multiple choices for simulating interactive user input via system.promt_answers.

Script authors have to cast their delegates to this type by wrapping them via a call to MultipleChoiceSelector().

Example::
def MyFilter(choice):

return choice in (“erste”, “zweite”, “dritte”)

system.prompt_answers[“my message key”] = PromptChoiceFilter(MyFilter)

Parameters:
choices (list[str]) – The choices.

Return type:
int

Returns:
The index of the accepted choice.

ScriptSystem.PromptCustomControlValueProvider(self, control_id)
Delegate for providing values for the options of a custom control for simulating interactive user input via system.prompt_answers. Script authors have to cast their delegates to this type by wrapping them via a call to PromptCustomControlValueProvider().

Example::
def MyFilter(control_id):
if control_id == id1:
return “value_for_id1”

if control_id == id2:
return “value_for_id2”

return None

system.prompt_answers[“my message key”] = (prompt_result_to_use, PromptCustomControlValueProvider(MyFilter))

Parameters:
control_id (str) – The id of the subcontrol e.g. a text field.

Return type:
str

Returns:
A string representing the value, that should be set for the given control. If None or an empty string is returned, the default / preset value is used.

classScriptSystem.ScriptCommand
Bases: object

Represents a CoDeSys command (Menu, Toolbar, Context Menu).

propertyname
Gets the display text of this command. This string is used as menu item label and usually is localized.

Return type:
str

 propertydescription
Gets the description for this command. This string is used as statusbar text and usually is localized.

Return type:
str

 propertytokens
Gets the tokens which introduce a corresponding batch instruction.

For example, a batch command which opens a project file would probably return the two tokens “file” and “open” here.

Return type:
list[str]

 propertyguid
Gets the GUID.

Return type:
Guid

classScriptSystem.ScriptCommands(iterable=(), /)
Bases: list

A sequence of all known Commands in CoDeSys.

classScriptSystem.ScriptObjectFactory
Bases: object

An Object factory.

propertyguid
Gets the GUID of the object factory.

Return type:
Guid

 propertyobject_type
Gets the guid of the produced object type.

Return type:
Guid

 propertyobject_namespace
Gets a GUID identifying the namespace the created object will belong to.

Return type:
Guid

 propertyname
Gets the display text of this object factory. This string should be localized.

Return type:
str

 propertydescription
Gets the description for this object factory. This string should be localized.

Return type:
str

classScriptSystem.ScriptObjectFactories(iterable=(), /)
Bases: list

A sequence of all known object factories.

search_factories_for(typeguid)
Returns all known object factories for a given object type.

The list is ordered, so that perfect matches (which produce exactly the queried type) come before factories which produce subclasses of the queried type. For object permission management, permissions are tested for the first factory of that list which produces that actual type.

Parameters:
typeguid (Guid) – The typeguid

Return type:
list

Returns:
A (possibly empty) sequence of object factories.

ScriptIecLanguageObjectContainer
classScriptIecLanguageObjectContainer.PouType(value)
Bases: Enum

Defines the type of the POU which is to be created.

Version added:
3.5.9.0

Program= 1
A Program.

FunctionBlock= 2
A function block.

Function= 3
A function.

classScriptIecLanguageObjectContainer.DutType(value)
Bases: Enum

Defines the type of the DUT which is to be created.

Version added:
3.5.9.0

Structure= 1
A structure.

Enumeration= 2
An enumeration.

Alias= 3
An alias.

Union= 4
A union.

EnumerationWithTextList= 5
An enumeration with integrated text list support.

classScriptIecLanguageObjectContainer.SpecialPouType(value)
Bases: Enum

Defines the type of special POUs (with implicit checks) which have to be created.

Version added:
3.5.12.10

none= 1
No special POU.

check_bounds= 2
Bound checks.

Appropriate handling of bound violations; such handling includes setting flags or changing field indices.

check_pointer= 3
Pointer checks.

check_range_unsigned= 4
Check range unsigned.

check_range_signed= 5
Check range signed.

check_div_real_64= 6
Check division real 64 bit.

check_div_real_32= 7
Check division real 32 bit.

check_div_int_64= 8
Check division real 64 bit.

check_div_int_32= 9
Check division real 32 bit.

check_l_range_unsigned= 10
L-range checks unsigned.

check_l_range_signed= 11
L-range checks signed.

classScriptIecLanguageObjectContainer.ScriptIecLanguageObjectContainer
Bases: object

This allows objects to create POU like objects, the methods will be available in the project root as well as applications, and folders below them.

The extended settings and specializations which are available in the “Add Object” dialog, but not available in this interface, can be implemented by direct access of the textual declaration part via ScriptObjectWithTextualDeclaration - for example, setting derived interfaces, or persistent or constant GVLs.

Version added:
3.5.9.0

create_pou(type: SpecialPouType)
Creates a POU with implicit checks according to the specified type.

Adding a check function will provoke a full recompile and prohibit an online change.

Version added:
3.5.12.10

Parameters:
type (SpecialPouType) – The SpecialPouType which should be created.

Raises:
Exception – Any exception which might occur (e. G. if an object with the same name already exists within the same namespace or the object cannot be created under this parent.

Return type:
ScriptObject

Returns:
The ScriptObject of the newly created POU.

create_gvl(name)
Creates a GVL with the specified name.

Parameters:
name (str) – The name.

Raises:
Exception – Any exception which might occur (e. G. if the name is not an IEC identifier, or an object with the same name already exists within the same namespace, or the language guid is not valid, or the object cannot be created under this parent.

Return type:
ScriptObject

Returns:
The ScriptObject of the newly created GVL.

create_dut(name, type=DutType.Structure, baseType=None)
Creates a DUT with the specified name and type.

As with manual object creation in the UI, enums will get the attribute ‘strict’ with compiler versions >= 3.5.7.0, and additionally the attribute ‘qualified_only’ with compiler version 3.5.8.0.

Parameters:
name (str) – The name.

type (DutType) – The type.

baseType (str) – The base type. This optional parameter is necessary for for Alias types, optional for STRUCTs and enums, and currently not allowed for unions.

Raises:
Exception – Any exception which might occur (e. G. if the name is not an IEC identifier, or an object with the same name already exists within the same namespace, or the language guid is not valid, or the object cannot be created under this parent.

Return type:
ScriptObject

Returns:
The ScriptObject of the newly created DUT.

create_interface(name, baseInterfaces='__System.IQueryInterface')
Creates an interface with the specified name.

Parameters:
name (str) – The name.

baseInterfaces (str) – The base interfaces (comma separated).

Raises:
Exception – Any exception which might occur (e. G. if the name is not an IEC identifier, or an object with the same name already exists within the same namespace, or the language guid is not valid, or the object cannot be created under this parent.

Return type:
ScriptObject

Returns:
The ScriptObject of the newly created interface.

create_persistentvars(name)
Creates a persistent GVL with the specified name.

Parameters:
name (str) – The name.

Raises:
Exception – Any exception which might occur (e. G. if the name is not an IEC identifier, or an object with the same name already exists within the same namespace, or the language guid is not valid, or the object cannot be created under this parent.

Return type:
ScriptObject

Returns:
The ScriptObject of the newly created persistent GVL.

classScriptIecLanguageObjectContainer.ScriptIecLanguageMemberContainer
Bases: object

This allows objects to create POU like member objects, the methods will be available on POUs, Interfaces, GVLs, and folders below them.

The extended settings and specializations which are available in the “Add Object” dialog, but not available in this interface, can be implemented by direct access of the textual declaration part via ScriptObjectWithTextualDeclaration - for example, setting derived interfaces, or persistent or constant GVLs.

Version added:
3.5.9.0

See also: ScriptTreeObject

create_property(name, return_type='int', language=None)
Creates a property with the specified name and type.

Parameters:
name (str) – The name.

return_type (str) – The return type.

language (Guid or None) – The language for the getter and setter. Optional, the default is structured text. It is illegal to specify a language for interface properties.

Raises:
Exception – Any exception which might occur (e. G. if the name is not an IEC identifier, or an object with the same name already exists within the same namespace, or the language guid is not valid, or the object cannot be created under this parent.

Return type:
ScriptObject

Returns:
The ScriptObject of the newly created property.

create_method(name, return_type=None, language=None)
Creates a method with the specified name and type.

Methods cannot be added to GVLs or Functions.

Parameters:
name (str) – The name.

return_type (str) – The return type.

language (Guid or None) – The language for the getter and setter. Optional, the default is structured text.

Raises:
Exception – Any exception which might occur (e. G. if the name is not an IEC identifier, or an object with the same name already exists within the same namespace, or the language guid is not valid, or the object cannot be created under this parent.

Return type:
ScriptObject

Returns:
The ScriptObject of the newly created method.

create_action(name, language=None)
Creates an action with the specified name and type.

Actions cannot be added to GVLs or Functions.

Parameters:
name (str) – The name.

language (Guid or None) – The language for the getter and setter. Optional, the default is structured text.

Raises:
Exception – Any exception which might occur (e. G. if the name is not an IEC identifier, or an object with the same name already exists within the same namespace, or the language guid is not valid, or the object cannot be created under this parent.

Return type:
ScriptObject

Returns:
The ScriptObject of the newly created action.

create_transition(name, language=None)
Creates an transition with the specified name and type.

Transitions cannot be added to GVLs or Functions.

Parameters:
name (str) – The name.

language (Guid or None) – The language for the getter and setter. Optional, the default is structured text.

Raises:
Exception – Any exception which might occur (e. G. if the name is not an IEC identifier, or an object with the same name already exists within the same namespace, or the language guid is not valid, or the object cannot be created under this parent.

Return type:
ScriptObject

Returns:
The ScriptObject of the newly created transition.

classScriptIecLanguageObjectContainer.ScriptImplementationLanguage
Bases: object

Defines the Guids for the standard IEC 61131-3 languages and those available as CODESYS extensions.

An instance of this interface will be injected with the name “ImplementationLanguages”.

Version added:
3.5.9.0

propertyst
Gets the language guid for ST / Structured Text.

Return type:
Guid

 propertycfc
Gets the language guid for CFC / Continous Flow Chart (free layout FUP).

Return type:
Guid

 propertypage_oriented_cfc
Gets the language guid for Page oriented CFC / Continous Flow Chart (free layout FUP).

Return type:
Guid

 propertyfbd
Gets the language guid for FBD / Function Block Diagram (FBS).

Return type:
Guid

 propertyinstruction_list
Gets the language guid for IL / Instruction List (AWL).

Return type:
Guid

 propertyladder
Gets the language guid for LD / Ladder Diagram (KOP).

Return type:
Guid

 propertysfc
Gets the language guid for SFC / Secuential Function Chart (AS).

Currently, SFC cannot be used for ScriptIecLanguageObjectContainer.create_pou() with PouType.Function, ScriptIecLanguageMemberContainer.create_method(), ScriptIecLanguageMemberContainer.create_property() and ScriptIecLanguageMemberContainer.create_transition().

Return type:
Guid

 propertyuml_statechart
Gets the language guid for the uml statechart.

The UML AddOn needs to be installed for this language. See also: http://store.codesys.com/codesys-uml.html

Return type:
Guid

ScriptLiveDeviceUserManagement
classScriptLiveDeviceUserManagement.ScriptLiveDeviceUserManagement
Bases: object

This object represents the live user management on a given device.

Version added:
3.5.16.0

propertyonline_device
Gets the online device this user management is using.

Return type:
ScriptOnlineDevice

 propertyusers
Gets the users on the device.

Return type:
ScriptLiveDeviceUserList

 propertygroups
Gets the groups on the device.

Return type:
ScriptLiveDeviceGroupList

upload()
Uploads the user and group information from the device.

backup(directory, password)
Backups the user management from the device.

Don’t change the name of the backup file because the device uses a fixed file name. Use different directories to store different backups.

Parameters:
directory (str) – Directory where the backup file shall be stored.

password (str) – Password which should be used to protected the backup file.

Return type:
str

Returns:
Full path of the backup file.

restore(path, password)
Restores the user management to the device.

Note

After the restore of the user management it is possible to get an authentication exception during the next operation on the online device because the current login session is no longer valid. In this case you catch the exception, reconnect the online device and repeat the operation.

For example:

online_device = online.create_online_device(device_obj)
user_mgmt = online_device.create_live_user_management()
user_mgmt.restore(file, password)
try:
    user_mgmt.upload()
except:
    online_device.disconnect()
    online_device.connect()
    user_mgmt.upload()
Parameters:
path (str) – Path of the backup file.

password (str) – Password which was used to protect the backup file.

add_user(name, password, can_change_password=True, must_change_password=False)
Adds a new user with the specified name.

Parameters:
name (str) – The name of the new user.

password (str) – Password for the new user.

can_change_password (bool) – User can change their password.

must_change_password (bool) – User must change their password with next login.

remove_user(name)
Removes the user with the specified name.

Parameters:
name (str) – The name of the existing user.

set_user_password(name, password)
Sets the password for this user.

Parameters:
name (str) – The name of the user.

password (str) – The password to set.

set_user_flags(name, flags)
Sets flags for the user.

Parameters:
name (str) – The name of the user.

flags (DeviceUserManagementFlags) – The flags to set.

add_group(name, group_members, user_members)
Adds a new group with the specified name.

Parameters:
name (str) – The name of the new group.

group_members (list[str]) – The group members of the new group.

user_members (list[str]) – The user members of the new group.

remove_group(name)
Removes the group with the specified name.

Parameters:
name (str) – The name of the existing group.

set_members_of_group(name, group_members, user_members)
Sets the members of groups and users which shall be in the group.

Parameters:
name (str) – The name of the group.

group_members (list[str]) – Group names which should be member for the group.

user_members (list[str]) – User names which should be member for the group.

classScriptLiveDeviceUserManagement.ScriptLiveDeviceUserList(iterable=(), /)
Bases: list

Represents a list of script device users.

Version added:
3.5.16.0

propertyflags
Gets flags concerning the entire user list.

Return type:
DeviceUserManagementFlags

classScriptLiveDeviceUserManagement.ScriptLiveDeviceGroupList(iterable=(), /)
Bases: list

A list of groups on the device.

Version added:
3.5.16.0

propertyflags
Gets flags concerning the entire group list.

Return type:
DeviceUserManagementFlags

classScriptLiveDeviceUserManagement.ScriptLiveDeviceUser
Bases: object

An user on the device.

Version added:
3.5.16.0

propertyflags
Gets flags concerning this particular user.

Return type:
DeviceUserManagementFlags

 propertyname
Gets the name of the user.

Return type:
str

classScriptLiveDeviceUserManagement.ScriptLiveDeviceGroup
Bases: object

A group of users, which have common rights on the device.

Version added:
3.5.16.0

propertyflags
Gets flags concerning this particular group.

Return type:
DeviceUserManagementFlags

 propertyname
Gets the name of the group.

Return type:
str

 propertyuser_members
Gets the user names which are member of this group.

Return type:
tuple[str]

 propertygroup_members
Gets the group names which are member of this group.

Return type:
tuple[str]

check_cyclic_membership(new_group_member)
Checks whether adding the specified group member would cause a cyclic membership dependency.

Parameters:
new_group_member (str) – The name of the new group membership to check.

Return type:
bool

Returns:
True if adding the specified group member would cause a cycle, False otherwise.

ScriptTextualObject
classScriptTextualObject.ScriptTextualObjectMarker
Bases: object

All tree objects get amended with this marker.

Version added:
3.5.6.0

propertyhas_textual_declaration
Gets a value indicating whether this ScriptObject has a textual declaration part.

Return type:
bool

Returns:
True if it has a textual declaration; otherwise False.

 propertyhas_textual_implementation
Gets a value indicating whether this ScriptObject has a textual implementation part.

Return type:
bool

Returns:
True if it has a textual implementation; otherwise False.

classScriptTextualObject.ScriptTextDocument
Bases: object

Interface for a text document, as it is used e. G. in textual declaration and implementation parts.

Line endings (’\n’, ‘\r’, ‘\r\n’) are normalized to ‘\n’. Lines do not include the line ending character. The first character has offset 0, the first line has lineno 0.

Version added:
3.5.6.0

propertylength
Gets the length of the text document in bytes.

Return type:
int

 propertylinecount
Gets the number of lines in the current text document.

Line endings (’\n’, ‘\r’, ‘\r\n’) are normalized to ‘\n’. Lines do not include the line ending character. The first line has lineno 0.

Return type:
int

 propertytext
Gets the complete text as a string.

Return type:
str

get_line(lineno)
Gets the line with the specified lineno.

Lines do not include the line ending character. The first line has lineno 0.

Parameters:
lineno (int) – The line number.

Return type:
str

Returns:
The line.

get_text(length, offset=None, lineno=None, lineoffset=None)
Gets the text.

Warning

The original C# function that is called with this method contains 2 overloads. It is strongly advised to pass all arguments with their respective keywords. offset, lineno and lineoffset are not actually optional, they just aren’t required in every overload. Pass them if your overload needs them!

get_text(self, offset, length) (1/2)

Gets the text at the specified offset.

Return type:
str

get_text(self, lineno, lineoffset, length) (2/2)

Gets the text at the specified lineno.

Parameters:
lineoffset (int) – The offset within the line.

Return type:
str

replace_line(lineno, line)
Replaces the complete line with the specified line number with the new text.

This method retains the position info of the text lines which are not modified.

append(text)
Appends the specified text at the end of the buffer.

This method retains the position info of the text lines which are not modified.

Parameters:
text (str) – The text.

insert(text, offset=None, lineno=None, lineoffset=None)
Insert text.

Warning

The original C# function that is called with this method contains 2 overloads. It is strongly advised to pass all arguments with their respective keywords. offset, lineno and lineoffset are not actually optional, they just aren’t required in every overload. Pass them if your overload needs them!

insert(self, offset, text) (1/2)

Inserts the text at the specified offset.

This method retains the position info of the text lines which are not modified.

insert(self, lineno, lineoffset, text) (2/2)

Inserts the text at the offset of the specified line.

This method retains the position info of the text lines which are not modified.

Parameters:
lineoffset (int) – The offset within the line.

Return type:
str

remove(length, offset=None, lineno=None, lineoffset=None)
Remove text.

Warning

The original C# function that is called with this method contains 2 overloads. It is strongly advised to pass all arguments with their respective keywords. offset, lineno and lineoffset are not actually optional, they just aren’t required in every overload. Pass them if your overload needs them!

remove(self, offset, length) (1/2)

Removes the text at the specified offset.

This method retains the position info of the text lines which are not modified.

remove(self, lineno, lineoffset, length) (2/2)

Removes the text at the specified offset of the specified line.

This method retains the position info of the text lines which are not modified.

Parameters:
lineoffset (int) – The offset within the line.

replace(new_text=None, newtext=None, length=None, offset=None, lineno=None, lineoffset=None)
Replace text.

Warning

The original C# function that is called with this method contains 3 overloads. It is strongly advised to pass all arguments with their respective keywords. No argument is actually optional, they just aren’t required in every overload. Pass them if your overload needs them!

replace(self, offset, length, newtext) (1/3)

Removes the text at the specified offset.

This method retains the position info of the text lines which are not modified.

Parameters:
newtext (str) – The new text.

replace(self, lineno, lineoffset, length, newtext) (2/3)

Removes the text at the specified offset of the specified line.

This method retains the position info of the text lines which are not modified.

Parameters:
lineoffset (int) – The offset within the line.

newtext (str) – The new text.

replace (self, new_text) (3/3)

Sets the specified new text.

This method erases the position info (used for bookmarks etc).

Parameters:
new_text (str) – The new text.

classScriptTextualObject.ScriptObjectWithTextualDeclaration
Bases: ScriptTextualObjectMarker

Accessor interface for textual declaration parts.

Version added:
3.5.6.0

propertytextual_declaration
Gets the textual declaration.

Return type:
ScriptTextDocument

classScriptTextualObject.ScriptObjectWithTextualImplementation
Bases: ScriptTextualObjectMarker

Accessor interface for textual implementation parts.

Version added:
3.5.6.0

propertytextual_implementation
Gets the textual implementation.

Return type:
ScriptTextDocument

ScriptApplication
classScriptApplication.ScriptApplicationMarker
Bases: object

Marker object to check whether a ScriptObject is an application object.

Version added:
3.5.2.0

propertyis_application
Gets a value indicating whether this ScriptApplicationMarker is an application.

Return type:
bool

Returns:
True if it is an application; otherwise, False.

classScriptApplication.ScriptApplication
Bases: ScriptApplicationMarker

ScriptObjects which are an application object are extended with this interface.

Version added:
3.5.2.0

propertyis_active_application
Gets a value indicating whether this.

ScriptApplication is the active application.

The active application is always in the primary project, so this property will always return false for non-primary projects.

Return type:
bool

Returns:
True if it is the active application; otherwise, False.

build()
Builds the application.

You can use the System.get_messages() and System.get_message_objects() calls to check whether any messages were added. This method only works for applications in the primary project.

clean()
Cleans the application.

You can use the System.get_messages() and System.get_message_objects() calls to check whether any messages were added. This method only works for applications in the primary project.

generate_code()
Generates the code for the application.

You can use the System.get_messages() and System.get_message_objects() calls to check whether any messages were added. This method only works for applications in the primary project.

rebuild()
Rebuilds the application.

You can use the System.get_messages() and System.get_message_objects() calls to check whether any messages were added. This method only works for applications in the primary project.

create_boot_application(output_filename, update_compile_info=False, write_visu_files=False)
Creates the offline boot project at the specified outputpath.

If the project was changed since the last download or online change to a PLC, and you create a boot application with update_compile_info set to true, this will overwrite the current compiler reference context with the one matching the boot project (which no longer matches the one on the PLC). Thus, a direct conline change to the PLC will no longer work. On the other hand, the reference context now matches the created boot application, so you can login to any PLC on which you deploy the generated boot application. This updated compile context is also the one to be included into a project archive.

Relative output filenames are interpreted relative to the location of the project. If you pass None or the empty string, applicationname.app is used. This method only works for applications in the primary project.

Version added:
3.5.5.0, available for 3.5.3.x from Patch 1

Parameters:
output_filename (str) – The filename to write the boot application to.

update_compile_file (bool) – if set to true, also writes the compile information (compiler reference context) to the project directory. (This may break online change, see below). (The compile information is updated in the directory where the project resides, not the output directory.)

write_visu_files (bool) – if set to true, also writes the visualization files into the output directory. It will be silently ignored when this application does not contain a visualization manager.

create_task_configuration()
Add the task configuration object to an application.

Version added:
3.5.10.0

Return type:
ScriptTaskConfigObject

Returns:
Script object of the task configuration object

propertyis_uptodate
Gets a value indicating whether this application is the same running on the PLC.

Version added:
3.5.10.0

Return type:
bool

Returns:
True if it is the same; otherwise, False.

 propertyis_online_change_possible
Gets a value indicating whether an online change is possible or not.

Version added:
3.5.10.0

Return type:
bool

Returns:
True if online change is possible; otherwise, False.

ScriptProject
classScriptProject.ComparisonFlags(value)
Bases: Enum

Flags controlling the details of the ScriptProject.compare_to() method.

Version added:
3.5.12.0

NONE= 0
No flags set.

IGNORE_WHITESPACE= 1
Controls whether whitespace changes are ignored (some object comparers ignore this parameter).

IGNORE_COMMENTS= 2
Controls whether comment changes are ignored (some object comparers ignore this parameter).

IGNORE_PROPERTIES= 4
Controls whether property changes are ignored (some object comparers ignore this propertyparameter).

SPLIT_RENAMES= 8
Controls whether renames are split into a add and remove operation. If set to True, renamed objects are recorded as addition and deletion. If set to False, renamed objects are marked with ScriptProject.ObjectDifferences.RENAMED.

COMPARE_TRANSIENTS= 16
Controls whether transient objects are ignored. Transient objects (like task call objects sitting below a ScriptTaskObject or SVN_VERSION_INFO objects) are not saved with the project, they’re based on data stored elsewhere and will be recreated on the fly, thus they’re not compared by default.

COMPARE_HIDDEN= 32
Controls whether hidden objects are ignored. As they’re not visible to the user, and usually represented by some other visible objects, they’re not compared by default.

classScriptProject.ObjectDifferences(value)
Bases: Enum

Representing the object differences.

Version added:
3.5.12.0

EQUAL= 0
The objects are equal.

ADDED= 1
The object was added.

DELETED= 2
The object has been deleted.

CONTENT_CHANGED= 4
The contents of the object are different.

FOLDER_CHANGED= 8
The parent folder of the object is different.

ACCESS_RIGHTS_CHANGED= 16
The acces rights of the object are different.

PROPERTIES_CHANGED= 32
The mets properties of the object are different.

RENAMED= 64
The name of the object was changed.

ANY_CHANGES= 16777215
This covers any changes we can detect now and in the future. (=0xFFFFFF)

classScriptProject.NativeImportResult(value)
Bases: Enum

Enum that enumerates the possible results of a native XML import.

no_changes= 1
The import did not change anything at all.

ok= 2
The import was successful

skipped= 3
The import skipped some entries

errors= 4
Errors happened during the import

classScriptProject.NativeImportResolve(value)
Bases: Enum

How to resolve a conflict.

replace= 1
Replace the object.

skip= 2
Skip the object

cancel= 3
Cancel the import

classScriptProject.Formatting(value)
Bases: Enum

none= (1,)
Indented= 2
classScriptProject.ConflictResolve(value)
Bases: Enum

Possible resolvements in the case that importing a specific PLCopenXML object leads to conflicts with an already existing object.

Replace= (0,)
The existing object is replaced by the imported object.

Copy= (1,)
The existing object remains with its original name, and the imported object is renamed so that is does not conflict any more.

Skip= 2
The object to be imported is skipped.

classScriptProject.ScriptProject
Bases: ScriptTreeObject

Provides project specific functionality to scripts.

close()
Closes this project.

The corresponding Object Manager project will also be closed. If this project has got unsaved changes, these changes will be discarded.

save()
Saves this project at its physical location (see path).

The encryption settings are not changed.

save_as(path, password=None)
Saves the project under a new filename and with different encryption.

If no password is given (None is passed), encryption stays as it is. If the password given, but an empty string, encryption is disabled. Otherwise, the password is used as new password to encrypt the project.

Note

If you want to change password without changing the path, use “proj.save_as(proj.path, “myPassword”)”.

Parameters:
path (str) – The new path to save the project.

password (str or None) – The password.

save_archive(path, comment=None, additional_files=None, *additional_categories)
Saves the project as an archive.

All additional categories which are selected by default are included, but no extra files.

Note

For a definition of the additional items, see ScriptProjectArchiveCategories. If you don’t pass any additional_categories, ScriptProjectArchiveCategories.@default is used. To exclude all additional items, explicitly pass None.

Parameters:
path (str) – The path to save the archive.

comment (str) – The comment to set for the archive.

additional_files (list) – The additional (external) files to include into the archive.

additional_categories (ScriptProjectArchiveCategory) – Version added: 3.5.4.0 The additional_categories.

propertydirty
Gets a boolean value indicating whether this project has been changed since the last call to save().

Return type:
bool

Returns:
True if this instance is dirty; otherwise, False.

 propertyprimary
Gets a boolean value indicating whether the primary attribute has been set for this project.

The primary project is the one the user is currently working with.

The other, non-primary projects (aka background projects) can serve several purposes, for example:

Libraries referenced by the primary project.

Projects opened for comparison by the “Compare Project” command.

Temporary projects created for various purposes, e. G. by the V2.3 import converter,

or the CODESYS SVN add-on.

Those projects are not directly user visible, and you should not modify or close them from within your scripts.

Return type:
bool

Returns:
True if this instance is primary; otherwise, False.

 propertylibrary
Gets a boolean value indicating whether the project is a background library project.

Those projects represent a library which was loaded because it is referenced by the primary project (directly or indirectly). It will automatically be closed when the primary project is closed.

If you want to check whether the primary project is a library or not, check whether the path() ends with “.library” or “.project”.

Return type:
bool

Returns:
True is this instance is a library; otherwise, False

 propertypath
Gets the absolute path where this project is physically stored.

To change that path, use save_as().

Return type:
str

 propertyactive_application
Gets or sets the active application.

This is a property. You can read or assign a ScriptObject for the application you want to be the active application.

Return type:
ScriptObject

document(objects)
Prints the specified database objects, including chapter headings and chapter numbering, a title page and table of contents.

The current printer settings as specified by the user are used. Currently, printing only works when the UI is present, not in –noUI mode.

Parameters:
objects (tuple[ScriptObject]) – The objects.

Raises:
InvalidOperationException – Is thrown when running in –noUI mode.

export_xml(objects, reporter=None, path=None, recursive=False, export_folder_structure=False, declarations_as_plaintext=False)
Exports the given objects in PLCopenXML format into a string, or a file at the given path.

All non-exportable objects are reported as error, but the export may still continue.

Parameters:
objects (tuple[ScriptObject]) – The objects to export.

reporter (ExportReporter) – The ExportReporter instance. None can be passed for no reporting.

path (str or None) – The path of the file we export into. If omitted, we export into a string and return that string.

recursive (bool or None) – If set to True, all exportable children of the objects are also exported.

export_folder_structure (bool) – Version added: 3.4.4.0 if set to True, the folder structure of the objects is also exported. This is a proprietary extension to the default schema.

declarations_as_plaintext (bool) – Version added: 3.5.2.0 if set to true, the declaration parts will be additionally exported as plain text (which is lossless in contrast to the default schema). This is a proprietary extension to the default schema. (Import will automatically recognize and prefer the plain text format if present.)

Return type:
str

Returns:
The exported XML as string, or None if a filepath is given.

import_xml(dataOrPath, reporter=None, import_folder_structure=False)
Imports the contents of the specified PLCopenXML file into the top level of the project.

The heuristics to find out whether the content is a file or directly an XML string currently is as follows: if it contains the ‘&lt;’ character, it is regarded as an XML file. Rationale: On windows, &lt; is an invalid char in path names, and it is contained in every XML file. (On other common platforms like unix and OSX, &lt; is uncommon and discouraged in file names.) This heuristics may be replaced by a more sophisticated heuristics in the future.

Parameters:
reporter (ImportReporter) – The import reporter.

dataOrPath (str) – The PLCopenXML file path, or the PLCopenXML as string.

import_folder_structure (bool or None) – Version added: 3.4.4.0 if set to true, the folder structure of the objects is also imported. This is a proprietary extension to the default schema.

export_native(objects, destination, recursive=False, one_file_per_subtree=False, profile_name=None, reporter=None)
Export the specified objects in the CoDeSys native export format.

The parameter destination must point to a directory if one_file_per_subtree is set to True, and to a file in the other case.

Version added:
3.4.4.0

Parameters:
objects (list) – The objects to export.

destination (str) – The destination.

recursive (bool) – if set to true, the chilren are included recursively.

one_file_per_subtree (bool) – if set to true, one file per subtree is generated.

profile_name (str) – The profile_name, or None for the default profile.

reporter (NativeExportReporter) – The reporter. You can pass None for no reporting at all.

import_native(filename=None, filenames=None, filter=None, handler=None)
Imports the specified files in the native xml format in the top level of this project.

Warning

If None is passed for both filename and filenames, this method will fail.

Version added:
3.4.4.0

Parameters:
filename (str) – The Filename.

filenames (list) – The Filenames.

filter (NativeImportFilter()) – The filter - if None is passed, all files are imported.

handler (NativeImportHandler) – The handler - if None passed, the default handler is used.

Return type:
NativeImportResult

login(username, password)
Log into the project using the specified credentials.

Version added:
3.4.1.10

Parameters:
username (str) – The username.

password (str) – The password.

logout()
Log out from the project (back to the user “nobody”).

Version added:
3.4.1.10

propertyuser_management
Returns the user management object for this project.

Version added:
3.5.1.0

Raises:
Exception – If no user management is available.

Return type:
ScriptUserManagement

 propertyhas_project_info
Gets a value indicating whether this ScriptProject already has a project information object.

Version added:
3.5.2.0

Return type:
bool

Returns:
true if it has a project info; otherwise, false.

get_project_info()
Gets the project information object, implicitly creating one if not existing yet.

Version added:
3.5.2.0

Return type:
ScriptObject

Returns:
The project information object.

check_all_pool_objects()
Checks all pool objects. This command only works reliable for libraries, and when called on primary projects.

You can use the System.get_messages() and System.get_message_objects() calls to check whether any messages were added.

Version added:
3.5.2.0

generate_runtime_system_files(destination_directory, generate_m4=True, generate_c=False)
Generates the specified destination_directory.

At least one of generate_m4 and generate_c must be set.

Version added:
3.5.2.0

Parameters:
destination_directory (str) – The destination_directory. Relative pathes are interpreted relative to the project location. If you pass None or the empty string, the project directory is used.

generate_m4 (bool) – if set to true, M4 code is generated.

generate_c (bool) – if set to true, C Code is generated.

clean_all()
Performs a “Clean All”.

Version added:
3.5.2.0

save_as_compiled_library(destination_name=None)
Save the current project as a compiled library.

This command currently only works for the primary project.

The destination_name has the following semantics: If it is omitted or the empty string, the full project path will be used, with the extension changed to “.compiled_library”. If the name of an existing directory is given, the library will be saved there, using the project base name and the extension changed to “.compiled_library”. Otherwise, the destination name will be interpreted as the path relative to where the current project re.

Version added:
3.5.2.0

Parameters:
destination_name (str or None) – The destination name.

create_folder(foldername, structured_view=None)
Creates a folder with the specified folder name.

There are three predefined structured views, and the guids are provided as constants:

SV_DEV The device view, SV_DEV = Guid("{D9B2B2CC-EA99-4c3b-AA42-1E5C49E65B84}")

SV_POU The POU view, SV_POU = Guid("{21AF5390-2942-461a-BF89-951AAF6999F1}")

The Modules View currently does not support folders, so no GUID is provided.

Version added:
3.5.2.0

Parameters:
foldername (str) – The foldername.

structured_view (Guid) – The structured view. This parameter is optional, if you pass Guid.Empty or omit the parameter, the “POU” view is used.

export_doc(path=None, ext_path=None, formatting=Formatting.Indented)
Exports the documentation for primary project in JSON format into a string, or a file at the given path.

Version added:
3.5.5.0

Parameters:
path (str or None) – The path of the file we export into. If omitted, we export into a string and return that string.

ext_path (str or None) – The path where external documentation files should be exported. If ommited, the same path as in path is used. If both ommited, the external documentation media is ignored.

formatting (Formatting) – Formatting of the export file.

Return type:
str

Returns:
The exported JSON as string, or None if a filepath is given.

compare_to(right_project, flags=0)
Compares two script projects.

Version added:
3.5.12.0

Parameters:
right_project (ScriptProject) – The project (base) you want to compare the current project against.

flags (ComparisonFlags) – Flags controlling the detailed behaviour of the comparison.

Return type:
ScriptComparisonResult

Returns:
The comparison result.

propertyproject_settings
Returns the management object for ScriptProjectSettings.

Version added:
3.5.12.10

Return type:
ScriptProjectSettings

enable_integrity_check()
Enables the integrity checked project format.

Version added:
3.5.13.0

disable_encryption()
Disables password, CodeMeter(TM) dongle and X509 certificate-based encryption or integrity check for the specified project.

Version added:
3.5.13.0

is_integrity_check_enabled()
Returns whether the integrity checked project format is is_integrity_check_enabled.

Version added:
3.5.13.0

Return type:
bool

classScriptProject.ScriptProjectSettings
Bases: object

Interface for project settings.

Version added:
3.5.12.10

propertyavailable_download_content
Gets a list of all available ScriptProjectArchiveCategories that can be used for ScriptProjectSettings.set_sourcedownload().

Return type:
list[ScriptProjectArchiveCategory]

set_sourcedownload(timing, content, compact, device)
Sets the source download settings to the project.

Parameters:
timing (int) –

The timing behaviour.¶
Value

Behaviour

1

Implicity at download and online change.

2

Prompt at program download and online change.

3

Implicity at creating boot project.

4

Only on demand.

5

Implicitly at creating boot project, program download and onlinechange.

content (list[ScriptProjectArchiveCategory]) – An enumerable of ScriptProjectArchiveCategory that should be part of the source download.

compact (bool) – Indicates to use a compact download or not.

device (ScriptObject) – The destination device or None for all devices in project.

propertyproject_defines
Gets or sets the project defines (a comma separated list).

This is a property. You can read or assign a string (a comma separated list) containing the project defines. This property can be only used for compilerversion 3.5.20.0 or newer.

Return type:
str

Returns:
The project defines, or an empty string if no project defines are set or the compilerversion is less than 3.5.20.0.

classScriptProject.ScriptComparedObject
Bases: object

Representing the difference of an object.

propertyleft_object
The object from the ScriptComparison.left_project, or None for deleted objects.

Return type:
ScriptObject

 propertyright_object
The object from the ScriptComparisonResult.right_project, or None for added objects.

Return type:
ScriptObject

 propertyObjectDifferences
The exact object differences.

Return type:
ObjectDifferences

classScriptProject.ScriptComparisonResult(iterable=(), /)
Bases: list

Represents the project comparison result.

Iterating this returns all changed objects.

Version added:
3.5.12.0

propertyleft_project
The first or left project which was compared.

Return type:
ScriptProject

 propertyright_project
The second or right project which was compared.

Return type:
ScriptProject

get_changed_objects(state=ObjectDifferences.ANY_CHANGES)
Returns all changed objects with a matching diff state (any of the given flags have to be set).

Parameters:
state (ObjectDifferences) – The diff states to filter for objects.

Return type:
list

Returns:
The objects matching the criteria.

get_diff_state(script_object)
Gets the diff state for a specific object.

Return type:
ScriptComparedObject

Returns:
The diff state for the object.

classScriptProject.ExportReporter
Bases: object

python classes can implement their own export_xml reporter here. This interface(IExportReporter) is exposed under the name ExportReporter.

error(obj, message)
This method is called when an error has occurred during export_xml.

Parameters:
obj (ScriptObject) – The object which caused the error.

message (str) – The message describing the problem.

warning(obj, message)
This method is called when a warning has occurred during export_xml.

Parameters:
obj (ScriptObject) – The object which caused the warning.

message (str) – The message describing the problem.

nonexportable(obj)
This method is called when we find out that a given object is not exportable.

This is only called for objects given directly as parameters - non-exportable children are silently ignored. The script can decide to abort the export by setting aborting to true during this phase.

This method will be called for all non-exportable objects even when aborting is set to true. The flag will be checked after all objects have been checked for exportability, just before the actual export is going to start (and thus before the destination file is opened). This allows scripts to find out about all non-exportable objects in one run.

Parameters:
obj (ScriptObject) – The object which is not exportable

propertyaborting
This allows abortion when we report non-exportable objects.

Return type:
bool

classScriptProject.ImportReporter
Bases: object

Python classes can implement their own import_xml reporter here.

This interface(IImportReporter) is exposed under the name ImportReporter.

error(message)
This method is called when an error has occurred during import_xml.

Parameters:
message (str) – The message describing the problem.

warning(message)
This method is called when a warning has occurred during import_xml.

Parameters:
message (str) – The message describing the problem.

resolve_conflict(obj)
This method is called when an object to import is already existing.

Parameters:
obj (ScriptObject) – The already existing object.

Return type:
ConflictResolve

Returns:
How to resolve the conflict: rename the new object, replace the existing object, or skip the new object.

added(obj)
This method is called whenever an object has been successfully added during import.

Parameters:
obj (ScriptObject) – The newly added object.

replaced(obj)
This method is called whenever an object has been successfully replaced during import.

Parameters:
obj (ScriptObject) – The replacing object.

skipped(objectname)
This method is called whenever an object has been skipped during import.

Parameters:
objectname (str) – The name of the skipped object.

propertyaborting
Gets a boolean value indicating whether importing should be aborted or not.

Return type:
bool

classScriptProject.NativeExportReporter
Bases: object

This reporter is used for the native XML export. This interface is exposed under the name NativeExportReporter.

skipped(type_name, serializable_value_name)
This method is called when data has been effectively skipped during serialization or deserialization.

Parameters:
type_name (str) – The typename of the object that was not stored or restored completely.

serializable_value_name (str) – The serializable value name of the member or property that has been skipped.

warn(message)
This method is called when a warning occurs during serialization or deserialization.

Parameters:
message (str) – A message describing the reason of the warning.

cancel(message)
This method is called when an error occurs during serialization or deserialization.

The code that triggered the serialization should discard the resulting stream because it will not be correctly formatted in this case. The code that triggered the deserialization should discard the resulting object because it might be inconsistent.

Parameters:
message (str) – A message describing the reason of the error.

ScriptProject.NativeImportFilter(self, name, guid, type, path)
[Delegate]. This method can be used to filter the imported objects.

Parameters:
path (tuple[object]) – A python tuple containing the object path.

Return type:
bool

Returns:
True if the item is to be imported.

classScriptProject.NativeImportHandler
Bases: object

Handler callback for the native XML import.

This interface is exposed under the name NativeImportHandler.

conflict(name, existingObject, newguid)
Queries how to resolve a conflict.

Return type:
NativeImportResolve

Returns:
The resolution for this conflict.

progress(name, pastedObject, exception)
Reports progress of import.

skipped(name)
Informs about skipped objects.

Parameters:
name (tuple[object]) – A python tuple with the names..

ScriptDeviceParameters
classScriptDeviceParameters.ScriptDeviceConnectorSet(iterable=(), /)
Bases: list

The readonly list of connectors for a specific device object.

get_device_object()
Gets the device object associated with this connector set.

Return type:
ScriptDeviceObject

by_id(id)
Gets the specific connector by its id.

Parameters:
id (int) – The id.

Return type:
ScriptDeviceConnector

Returns:
The connector

classScriptDeviceParameters.ScriptConnector
Bases: object

A connector.

This is implemented by the ScriptDeviceConnector instances returned by the ScriptDeviceConnectorSet as well as by ScriptExplicitConnectorObject.

propertymodule_type
Id of the connector. This id is used by the driver on the runtime system.

The Id’s of matching parent and child connectors are different. Therefore in order to find a matching device for a given parent connector use the ConnectorType Property instead.

Return type:
int

 propertyinterface
The unique typename of a connector, eg. “Common.PCI”.

A parent connector may be connected to a child connector, if this connector type matches.

Return type:
str

 propertyinterface_name
Get an internationalized version of the interface name for presentation purposes.

Return type:
str

 propertyconnector_id
The unique connector id.

Return type:
int

 propertyhost_path
Get the id of the next connector towards the host.

-1, if the attached device is the controlling host.

Return type:
int

 propertyconnector_role
Get whether this connector is a parent or child connector.

Return type:
ConnectorRole

 propertyis_explicit
Get whether a separate node should be shown in the user interface for this connector.

Return type:
bool

 propertyhost_parameters
Get the host parameter set of this connector.

The returned list is read-only which means you can’t add, insert or remove parameters or clear it. The list of available parameters is defined in the device description.

Return type:
ScriptDeviceParameterSet

get_device_object()
Get an instance of the device object this connector belongs to.

Return type:
ScriptDeviceObject

Returns:
The device object.

propertyadditional_interfaces
Gets the additional interfaces of the connector.

This may be useful to find out which child connector of the current parent connector is actually valid.

Version added:
3.5.6.0

Return type:
list

Returns:
A python tuple containing strings declaring the additional interfaces.

classScriptDeviceParameters.ScriptDeviceConnector
Bases: ScriptConnector

A device connector as contained in the ScriptDeviceConnectorSet.

propertyparent
Gets the ScriptDeviceConnectorSet defining this connector.

Return type:
ScriptDeviceConnectorSet

 propertyio_always_mapping
Gets a value indicating whether this ScriptDeviceConnector is always mapping the I/Os belonging to this connector, even if they’re not used in the IEC code.

By default, I/Os which are not used in the IEC code are not updated in the I/O task. For debugging and other purposes, this behaviour can be overridden with this property.

Version added:
3.5.8.0

Return type:
bool

 propertydriver_info
Get the driver info of the device connector.

Version added:
3.5.15.0

Return type:
ScriptDriverInfo

classScriptDeviceParameters.ScriptDeviceParameterSet(iterable=(), /)
Bases: list

A device parameter set.

The list is read-only which means you can’t add, insert or remove parameters or clear it. The list of available parameters is defined in the device description.

propertyparent
Gets the parent.

This is either a ScriptDeviceObject, a ScriptConnector, or a ScriptExplicitConnectorObject.

Return type:
obj

get_device_object()
Gets the device object or explicit connector object defining this parameter set.

Return type:
ScriptDeviceObject

by_id(id: int)
Gets the ScriptDeviceParameter with the specified id.

Return type:
ScriptDeviceParameter

classScriptDeviceParameters.ScriptMappableDeviceParameterSet(iterable=(), /)
Bases: ScriptDeviceParameterSet

Extension interface for the ScriptDeviceParameterSet returned by ScriptDeviceObject.device_parameters().

propertyio_always_mapping
Gets a value indicating whether this ScriptMappableDeviceParameterSet is always mapping the I/Os belonging to device parameter set (not part of any connectors), even if they’re not used in the IEC code.

By default, I/Os which are not used in the IEC code are not updated in the I/O task. For debugging and other purposes, this behaviour can be overridden with this property.

Return type:
bool

classScriptDeviceParameters.ScriptDataElement
Bases: object

A data element of an online parameter.

Notice that instances of this interface usually also implement at least one of the related interfaces ScriptCompoundDataElement, ScriptValueDataElement, ScriptDeviceParameter, ScriptCompoundDataElement, ScriptEnumerationDataElement, ScriptRangeDataElement, which contain additional useful members, e. G. ScriptValueDataElement.value. Which interface applies can be determined via the properties has_sub_elements, is_range_type, is_enumeration, is_union and parameter.

propertyparent
Gets the parent.

This property returns either the parent ScriptDataElement (which may be the ScriptDeviceParameter), or the ScriptDeviceParameterSet if the current element is the device parameter.

Return type:
obj

 propertyparameter
Gets the parameter defining this data element.

This will return the same instance if called on the ScriptDeviceParameter.

Return type:
ScriptDeviceParameter

 propertyidentifier
Unique identifier of this data element within it’s parent element.

Return type:
str

 propertyvisible_name
Internationalized name of the data element (this is the name used in the user interface).

Return type:
str

 propertydescription
Internationalized description of the data element.

Return type:
str

 propertyunit
Internationalized unit of the data element. To be used by the presentation layer.

Return type:
str

 propertybit_size
Get the size of this parameters value in bits.

Return type:
int

 propertyuser_comment
Get or set a specified user comment.

Return type:
str

 propertyhas_sub_elements
Get information whether this element is a compound type.

True for structs, arrays, bitfields, … - in this case, the element implements ScriptCompoundDataElement. If this is False, the element implements ScriptPrimitiveTypeDataElement. The properties is_enumeration and has_sub_elements are mutually exclusive, only one of them can be true at the same time.

Return type:
bool

 propertyis_range_type
True, if the elements value must be within a certain range.

If this is true, the element implements the ScriptRangeDataElement interface.

Return type:
bool

 propertyis_enumeration
True if this element is defined as an enumeration. It then also implements ScriptEnumerationDataElement.

The properties is_enumeration and has_sub_elements are mutually exclusive, only one of them can be true at the same time.

Return type:
bool

 propertyis_union
Gets a value indicating whether this ScriptDataElement is an union.

Return type:
bool

 propertycan_access_online
Gets a value indicating whether this ScriptDataElement can be read online.

If this is true, the element additionally implements ScriptValueDataElement.

Return type:
bool

 propertyis_mappable_io
Gets a value indicating whether this ScriptDataElement is a mappable input or output.

Version added:
3.5.8.0

Return type:
bool

Returns:
True if is a mappable input or output; otherwise, False.

 propertyio_mapping
Gets the io mapping of this data element.

Version added:
3.5.8.0

Return type:
ScriptIoMapping

Returns:
The mapping, or None if no mapping exists (e. G. the data element is a device parameter and not an input or output).

classScriptDeviceParameters.ScriptCompoundDataElement(iterable=(), /)
Bases: list

Data element representing compound values which cannot be read or written, but they have subelements which can be modified (if they’re not ScriptCompoundDataElements themselves).

Implementations of this interface also implement ScriptDataElement and sometimes also ScriptDeviceParameter.

classScriptDeviceParameters.ScriptValueDataElement
Bases: ScriptDataElement

Data element representing values of basic member elements which can be read and written.

propertydefault_value
Get the default value for this data element.

If the string is empty, then no explicit defaultvalue has been set.

Return type:
str

 propertyvalue
Set/get the value for this element as a string representation.

Invalid values are accepted, but cause the error flag to be set.

Raises:
InvalidOperationException – Thrown if this element is a compound type (struct, array, …) - in other words, when ScriptDataElement.has_sub_elements is True - in that case, you need to set the values of the sub elements.

Return type:
str

 propertybase_type
Gets the base type of this data element, or None if the type is a compound type.

Return type:
str

read_online_value(nTimeOut=1000)
Get the online value with the specified timeout.

You need to check ScriptDataElement.can_access_online before using this property.

Parameters:
nTimeOut (int) – The timeout.

Return type:
str

Returns:
The read value.

write_online_value(value)
Writes the specified value to the device.

You need to check ScriptDataElement.can_access_online before using this property.

Parameters:
value (str) – The value.

classScriptDeviceParameters.ScriptRangeDataElement
Bases: ScriptValueDataElement

Data element representing values with a limited range.

propertymin_value
Get the minimal value for this element as a string representation.

Raises:
InvalidOperationException – Thrown if this element is not a range type element (equivalent to IsRangeType == False).

Return type:
str

 propertymax_value
Get the maximum value for this element as a string representation.

Raises:
InvalidOperationException – Thrown if this element is not a range type element (equivalent to IsRangeType == False).

Return type:
str

classScriptDeviceParameters.ScriptEnumerationDataElement
Bases: ScriptValueDataElement

Data element representing enumeration values.

propertyenum_value
Set/get the current value for this element as an enumeration value.

Raises:
InvalidOperationException – Thrown if this element is not a valid enumeration element.

Return type:
ScriptEnumerationValue

 propertyallowed_values
Set/get the current value for this element as an enumeration value.

Invalid values are accepted, but cause the error flag to be set.

Raises:
InvalidOperationException – Thrown if this element is not a valid enumeration element.

Return type:
list[ScriptEnumerationValue]

 propertyvalue_index
Gets or sets the index of the current value within the allowed_values array.

Return type:
int

Returns:
-1 if the current value is not a valid enumeration value.

read_online_enum_value(nTimeout=1000)
Get_online_enum_values the specified n timeout.

You need to check ScriptDataElement.can_access_online before using this property.

Parameters:
nTimeout (int) – The timeout in milliseconds.

Return type:
ScriptEnumerationValue

Returns:
Teh enumeration value.

write_online_value(value)
Writes the specified value to the device.

You need to check ScriptDataElement.can_access_online before using this property.

Parameters:
value (ScriptEnumerationValue) – The value.

classScriptDeviceParameters.ScriptEnumerationValue
Bases: object

Defines one element of an enumeration.

propertyparent
Gets the defining ScriptEnumerationDataElement.

Return type:
ScriptEnumerationDataElement

 propertyidentifier
Unique identifier of this enumeration value within its enumeration element.

This is the value to use with the ScriptValueDataElement.value property.

Return type:
str

 propertyvisible_name
Internationalized name of the enumeration value. To be used by the presentation layer.

Return type:
str

 propertydescription
Internationalized description of the enumeration value. To be used by the presentation layer.

Return type:
str

 propertyvalue
Gets the value.

Return type:
str

 propertyindex
Gets the index of this value within the ScriptEnumerationDataElement.allowed_values list.

Return type:
str

classScriptDeviceParameters.ScriptDeviceParameter
Bases: ScriptDataElement

A device parameter.

propertyid
Each parameter has a unique id within it’s parameter list. This is also returned as the identifier in the underlying DataElement.

Return type:
int

 propertyname
Internationalized name of the data element. To be used by the presentation layer.

Return type:
str

 propertyoffline_access_rights
Get the allowed access to this parameter in offline mode.

Return type:
AccessRight

 propertyonline_access_rights
Get the allowed access to this parameter in online mode.

Return type:
AccessRight

 propertydownloaded_with_ioconfig
Get whether this parameter will be downloaded with the IO-Config.

Return type:
bool

 propertychannel_type
If this parameter represents an IO channel, returns whether it is an input or an output channel. Otherwise this property returns ChannelType.None.

Return type:
ChannelType

 propertydiagnostic_type
Get or set the diagnostic type of this parameter.

Return type:
DiagType

 propertytype_string
Returns a string which fully describes the type.

Return type:
str

 propertysection
Gets the section of the parameter.

The sections are purely informative and help to structure the device parameters in user interfaces.

Return type:
str

 propertyiec_type
Gets the iec type of this parameter, or None if none is defined.

Return type:
str

 propertyparam_type
get information about the original paramtype (e.g. “std:uint” or “localtypes:struct”).

Usually, this is the best method to describe the type of an parameter - however, in old projects, this value might not be accurate or even empty.

Return type:
str

get_device_object()
Gets the device object associated with this parameter.

Return type:
ScriptDeviceObject

propertydisable_mapping
Get whether this parameter will be in the task mapping list for the io drivers.

Version added:
3.5.12.20

Return type:
bool

classScriptDeviceParameters.ScriptIoVariableMapping
Bases: object

Represents a single variable mapping.

propertyId
Gets the identifier.

Return type:
int

 propertyvariable
Gets or sets the variable for the mapping.

The string must be a valid IEC variable expression. If it’s an unqualified expression, a new variable with the given name will be created. Qualified expressions define a mapping to an existing variable.

Return type:
str

 propertydefault_variable
Gets the default variable, if defined in the device description.

The default variable, if existing, is defined in the device description.

Return type:
str

 propertymapping_creates_variable
Gets a value indicating whether this ScriptIoVariableMapping creates a new variable.

This is the opposite of maps_to_existing_variable.

Return type:
bool

Returns:
True if it creates a new variable; otherwise, False.

 propertymaps_to_existing_variable
Gets a value indicating whether this ScriptIoVariableMapping maps to an existing variable.

This is the opposite of mapping_creates_variable.

Return type:
bool

Returns:
True if it maps to an existing variable; otherwise, False.

classScriptDeviceParameters.ScriptIoMapping
Bases: ScriptIoVariableMapping

Describing the I/O Mapping options. This object also represents the first actual mapping for the variable.

Currently the device IO mapping editor UI allows only a single mapping to be configured, so we’ll implicitly handle this mapping similar to what the device IO mapping editor does. When an output variable (or a member thereof) is a struct, either the struct itself or its components may be mapped, but not both, as the semantics of the colliding mappings is not clear.

propertyautomatic_iec_address
Gets or sets a value indicating whether this ScriptIoMapping has automatically assigned IEC addresses.

Return type:
bool

Returns:
True if the IEC addresses are automatically assigned; otherwise, False.

 propertymanual_iec_address
Gets or sets the manually assigned IEC address.

Setting this to None will set automatic_iec_address to True, setting this to an address will set automatic_iec_address to False.

Return type:
str

Returns:
The manually assigned IEC address, or the automatically assigned address if the IEC address is automatically assigned.

ScriptObject
classScriptObject.ScriptObject
Bases: ScriptTreeObject

Modelling of a script object.

They compare equal if Guid and ProjectHandle (inherited from ScriptTreeObject) are equal.

propertytype
Gets the type guid.

Return type:
Guid

 propertyguid
Gets the GUID of the object.

Return type:
Guid

 propertyembedded_object_types
Gets the embedded onject types.

Return type:
list[Guid]

get_name(resolve_localized_display_name=False)
Gets the name of the object.

Parameters:
resolve_localized_display_name (bool) – if set to True, the name is localized.

Return type:
str

Returns:
The name of the object

rename(stNewName)
Renames the object to the new name.

Parameters:
stNewName (str) – New name of the object.

propertyindex
Gets the index.

Return type:
int

 propertyis_folder
Gets a value indicating whether this instance is a folder.

Return type:
bool

 propertyparent
Gets the parent ScriptObject, or the Project if we are top-level.

You can use the is_root property implemented by objects and projects to distinct between the two.

Return type:
object

remove()
Removes this instance.

move(new_parent: ScriptProject, new_index: int = -1)
Moves the object to the specified new parent.

Parameters:
new_parent (ScriptProject) – The new parent.

new_index (int) – New index in the new parent.

export_xml(reporter=None, path=None, recursive=False, export_folder_structure=False, declarations_as_plaintext=False)
Exports the ScriptObject in PLCopenXML format into a string, or a file at the given path.

This method internally eliminates duplicates, and all non-exportable objects are reported as error. Following 3.5.4.0, reporter can be omitted. The method will then report all exportable objects, report everything on progress, and throw exceptions on critical errors.

Note

Due to the sheer amount of overrides from different versions this function has to offer, it is best practice to give even positional arguments with their respective keywords.

Parameters:
reporter (ExportReporter) – The IExportReporter instance.

recursive (bool) – if set to true, all exportable children of the objects are also exported.

path (str) – The path of the file we export into. If omitted, we export into a string and return that string.

export_folder_structure (bool) – Version added: 3.4.4.0 if set to true, the folder structure of the objects is also exported. This is a proprietary extension to the default schema.

declarations_as_plaintext (bool) – Version added: 3.5.3.0 if set to True, the declaration parts will be additionally exported as plain text (which is lossless in contrast to the default schema). This is a proprietary extension to the default schema. (Import will automatically recognize and prefer the plain text format if present.)

Return type:
str

Returns:
The exported XML as string, or None if a filepath is given.

import_xml(dataOrPath, conflictResolve=None, import_folder_structure=False, reporter=None)
Imports the contents of the specified PLCopenXML file als children of the current object.

The heuristics to find out whether the content is a file or directly an XML string currently is as follows: if it contains the ‘&lt;’ character, it is regarded as an XML file. Rationale: On windows, &lt; is an invalid char in path names, and it is contained in every XML. This heuristics may be replaced by a more sophisticated heuristics in the future. Following 3.5.4.0, reporter can be omitted.

Note

Due to the sheer amount of overrides from different versions this method has to offer, it is best practice to give even positional arguments with their respective keywords.

Parameters:
dataOrPath (str) – The PLCopenXML file path, or the PLCOpenXML as string.

conflictResolve (ConflictResolve) – The conflict resolution strategy.

import_folder_structure (bool) – Version added: 3.4.4.0 if set to true, the folder structure of the objects is also imported. This is a proprietary extension to the default schema.

reporter (ImportReporter) – The import reporter.

export_native(destination, recursive=True, profile_name=None, reporter=None)
Export the specified objects in the CoDeSys native export format.

Version added:
3.4.4.0

Parameters:
destination (str) – The destination file.

recursive (bool) – if set to true, the chilren are included recursively.

profile_name (str) – The profile_name, or None for the default profile.

reporter (NativeExportReporter) – The reporter. You can pass None for no reporting at all.

import_native(filenames, filter=None, handler=None)
Imports the specified files in the native xml format in under the current node.

Version added:
3.4.4.0

Parameters:
filenames (str or list) – The filename or a list of filenames.

filter (NativeImportFilter()) – The filter - if None is passed, all files are imported.

handler (NativeImportHandler) – The handler - if None passed, the default handler is used.

create_folder(foldername)
Creates a folder with the specified foldername in the structured view of the parent node.

The Modules View currently does not support folders, so creating folders below module objects is not supported.

Version added:
3.5.3.0

Parameters:
foldername (str) – The foldername.

get_signature_crc(application=None, default_value=None)
Gets the signature CRC of the specified pou.

A successful build is needed for this method to work.

For POUs which are defined below an application, compile the application via ScriptApplication.build(). You can omit “application”, and the parent application will be found automatically. For POUs which are in the pool of a library projuect, compile the application via ScriptProject.check_all_pool_objects(). The pool application guid (Guid.Empty) will be used automatically in this case, so you can omit “application”. For pous which are defined in the pool of a project, but referenced from within an application, compile the application via ScriptApplication.build() and explicitly pass that application (or its guid) as “application” parameter.

Version added:
3.5.4.0

Parameters:
application (object) – The application which the POU is referenced, if necessary (see remarks). This parameter accepts the application object or its guid.

default_value (str) – If you pass a value here, this is returned instead of throwing an exception when no CRC is found.

Return type:
string

Returns:
The string representation of the CRC, or the default value when no CRC was found.

Raises:
InvalidOperationException – No compile context found for the object - maybe the application was not compiled?

NotSupportedException – No compiled signature found for the object - maybe the object is no POU.

KeyNotFoundException – No CRC attribute found for the object.

ArgumentException – You passed an invalid object for the application.

propertybuild_properties
Gets the build properties of the object, or None.

Not all objects have editable build properties - this method returns None when the object does not have any build properties.

Version added:
3.5.7.0

Return type:
ScriptBuildProperties

 propertyeffectively_excluded_from_build
Gets a boolean indicating whether this object is effectively excluded from the build.

An object is effectively excluded if either the object itsself or any of its parents has the ScriptBuildProperties.exclude_from_build() flag set.

Version added:
3.5.7.0

Return type:
bool

 propertyexclusion_from_build_is_inherited
Gets a boolean indicating whether the build exclusion is inherited from a parent object.

Version added:
3.5.7.0

Return type:
bool

classScriptObject.ScriptBuildProperties
Bases: object

Defining the build properties of objects contributing to the compiler.

Note that some objects do not define all of those properties. For example, folders only allow the exclude_from_build() property to be set (which is inherited to POUs below that folder), and devices may opt in or out of some properties based on the kind of device. Accessing an invalid property will throw an InvalidOperationException.

propertyexternal
Gets or sets the External-flag.

A POU with this flag is supposed to be linked in runtime system.

Check the external_is_valid() property whether this property is currently valid for this object.

Return type:
bool

 propertyexternal_is_valid
Gets wether the external() property is valid for this object or not.

Return type:
bool

 propertyenable_system_call
Gets or sets the Enable system call-flag.

A POU with this flag can be called by C-Code out of the runtime system

Check the enable_system_call_is_valid() property whether this property is currently valid for this object.

Return type:
bool

 propertyenable_system_call_is_valid
Gets whether the enable_system_call() property is is valid for this object or not.

Return type:
bool

 propertycompiler_defines
Gets or sets compilerdefines for the object.

The defines may be a list of comma seperated defines like this: DEF1, DEF2=’value’ For simple objects the scope of these defines is the object itself for applications, the scope of these defines is the whole application. Check the compiler_defines_is_valid() property whether this property is currently valid for this object.

Return type:
str

 propertycompiler_defines_is_valid
Gets whether the compiler_defines() property is valid for this object or not.

Return type:
bool

 propertylink_always
Gets or sets the flag for linking an object in any case.

If true is assigned, the object will be linked into the application even when it is not referenced in another way.

Check the link_always_is_valid() property whether this property is currently valid for this object.

Return type:
bool

 propertylink_always_is_valid
Gets whether the link_always() property is valid for this object or not.

Return type:
bool

 propertyexclude_from_build
Gets or sets the flag Exclude from build.

Objects which are excluded from the build will be ignored by the compiler.

In other words, the language model of an object with this flag will be removed from language model manager. Note that a false value might be overwritten by a true value stored for the parent object. Use ScriptObject.effectively_excluded_from_build() to query the effective value for this object. Check the exclude_from_build_is_valid() property whether this property is currently valid for this object.

Return type:
bool

 propertyexclude_from_build_is_valid
Gets whether the exclude_from_build() property is valid for this object or not.

Return type:
bool

classScriptObject.ScriptProjectInfoMarker
Bases: object

The all objects are extended with this interface, since CoDeSys V3.5 SP2.

Version added:
3.5.2.0

propertyis_project_info
Gets a value indicating whether this ScriptProjectInfoMarker is the project info object.

Return type:
bool

classScriptObject.ScriptProjectInfoObject
Bases: ScriptProjectInfoMarker

The project information objects are extended with this interface, since CoDeSys V3.5 SP2.

Version added:
3.5.2.0

propertygenerate_accessors
Gets a value indicating whether this ScriptProjectInfoObject generates property accessor POU objects or not.

Returns:
true` if accessor functions are generated; otherwise, ``false.

Return type:
bool

change_accessor_generation(generate_accessors)
Changes the generate_accessor flag.

As changing this flag is potentially expensive (genrating several POUs), it is an explicit function and no property setter.

Parameters:
generate_accessors (bool) – if set to True, the accessors are generated.

propertycompany
Gets or sets the company.

Libraries are uniquely identified by the tuple <company(), title(), version()>

Return type:
str

 propertytitle
Gets or sets the title.

Libraries are uniquely identified by the tuple <company(), title(), version()>.

Return type:
str

 propertyversion
Gets or sets the version.

remarks

Return type:
Version or str or tuple[int] or Sequence[int]

Returns:
The version. This returns a System.Version instance. For setting, it accepts System.Version instances as well as strings which are parseable as version, and tuples / sequences with 2-4 integers.

 propertyreleased
Gets or sets a value indicating whether the project containing this ScriptProjectInfoObject is released.

Released library projects should not be modified any more. Unset the released flag and change the version if you want to modify a released library.

Return type:
bool

 propertycategories
If the project is used as a library, it appears under the following categories.

Return type:
list[LibCategory]

 propertydefault_namespace
Gets or sets the default namespace when the project is used as a library.

Return type:
str

 propertyauthor
Gets or sets the author.

Return type:
str

 propertydescription
Gets or sets the description.

This string may be multiline.

Return type:
str

 propertydongle_licencing_active
Gets or sets a value indicating whether this library has dongle license protection.

If dongle licensing is activated, the user needs to connect a dongle containing the appropriate license in order to use this library. For the licensing to work correctly, both firm_code and product_code MUST be specified. Please note that only compiled libraries will be protected!

Return type:
bool

Returns:
true if license protection is active; otherwise, false

Raises:
InvalidOperationException – When setting to True, but dongle_licensing_firm_code() or dongle_licensing_product_code() are not set.

 propertydongle_licensing_firm_code
Gets or sets the dongle licensing firm code.

If dongle licensing is activated, the user needs to connect a dongle containing the appropriate license in order to use this library. For the licensing to work correctly, both firm_code and product_code MUST be specified. Please note that only compiled libraries will be protected!

Return type:
int or None

Raises:
InvalidOperationException – When trying to unset this value while dongle_licencing_active() is set.

ArgumentOutOfRangeException – When trying to set this to a negative value.

 propertydongle_licensing_product_code
Gets or sets the dongle licensing product code.

If dongle licensing is activated, the user needs to connect a dongle containing the appropriate license in order to use this library. For the licensing to work correctly, both firm_code and product_code MUST be specified. Please note that only compiled libraries will be protected!

Return type:
int or None

Raises:
InvalidOperationException – When trying to unset this value while dongle_licencing_active() is set.

ArgumentOutOfRangeException – When trying to set this to a negative value.

 propertydongle_licensing_activation_url
Gets or sets the dongle licensing activation email address.

Return type:
str

 propertydongle_licensing_activation_mail
Gets or sets the dongle licensing activation email address.

Return type:
str

 propertyvalues
Gets the custom property dictionary.

The following types are allowed:

Type

Description

str

Textual properties.

DateTime

Date / time properties.

int

Numerical properties.

bool

Boolean properties.

Version

Version properties, they may also be passed as str or tuple / sequence of integers.

You’re responsible yourself to set the correct type. Any inconsistencies or problems introduced by fiddling with this dictionary are your own responsibility.

Some properties are defined in the online help: See the section “Libraries -> Guidelines for creating Libraries -> Library Development Summary -> CODESYS LibDevSummary V3.5.4.0 -> Concepts and Elements -> Library Properties”:

–

Name

Type

Description

Required

Company

Text

Serves for structuring (filter) in the “Add Library” dialog

Required

Title

Text

Name of the library

Required

Version

Version

Library verison

Optional

Released

Bool

A library should not be modified after having been released

Optional

Author

Text

Author of the current library version

Optional

DefaultNamespace

Text

World-wide unique prefix, for defining the scope of the symbols of the library

Optional

Description

Text

Short description of the purpose of the library

Optional

Placeholder

Text

which Placeholder should be used for referencing the library

Optional

IsContainerLibrary

Bool

This library follwos the rules for a Container Library

Optional

IsInterfaceLibrary

Bool

This library follows the rules for a Interface Library

Optional

LanguageModelAttribute

Text

The access on symbols of the library is only possible via Namespace/Prefix

Optional

IsEndUserLibrary

Bool

This Library is especially designed for the needs of end users

Return type:
Dictionary(str, object)

ScriptDriverInfo
classScriptDriverInfo.AlwaysUpdateVariablesMode(value)
Bases: Enum

Defines always mapping modes on a parameter or connectors.

Disabled= 1
Disable the always update of the variables.

OnlyIfUnused= 2
The io channel is mapped in the bus cycle task if no other task is using it. If it used in an task then alwaysmapping is ignored, because it is updated in the used task only.

AlwaysInBusCycle= 3
The io channel is always updated in the bus cycle task independent of the real task usage. Therefore task consistency is not guaranteed.

classScriptDriverInfo.ScriptDriverInfo
Bases: object

Provides access to the driver info of the device.

Mostly the visible parts of the tab “PLC Settings” in the device editor.

propertycan_set_io_application
Whether the IO application can be set.

Return type:
bool

 propertyio_application
Get/set the object Guid of the application which does the IO handling.

Return type:
Guid

set_io_application(application)
Set the application which does the IO handling.

Parameters:
application (ScriptApplication) – Script object of the application.

propertyupdate_ios_while_in_stop
Update IOs while in stop.

Return type:
bool

 propertybehaviour_for_outputs_on_stop
Get/set the behaviour for outputs on stop.

Return type:
StopResetBehaviour

 propertyuser_program_for_stop_reset_behaviour
Get/set the behaviour program for stop/reset if behaviour_for_outputs_on_stop is set to ExecuteProgram.

See also: StopResetBehaviour.ExecuteProgram

Return type:
str

 propertyalways_update_variables
Set the mode for (always) updating variables.

Return type:
AlwaysUpdateVariablesMode

 propertybus_cycle_task_by_name
Get the name of the bus cycle task.

Return type:
str

 propertybus_cycle_task_by_guid
Get the object guid of the bus cycle task.

Return type:
Guid

set_bus_cycle_task(task: ScriptObject)
Set the bus cycle task by name or object guid or script object.

Parameters:
task (ScriptObject) – Script Object of the task.

propertygenerate_force_variables
Generate force variables for IO mapping.

Return type:
bool

 propertyenable_diagnosis
Enable diagnosis for devices.

Return type:
bool

 propertyshow_io_warnings_as_errors
Show IO warnings as errors.

Return type:
bool

ScriptTaskConfigObject
classScriptTaskConfigObject.KindOfTask(value)
Bases: Enum

An enumeration.

Cyclic= (1,)
Freewheeling= (2,)
Event= (3,)
ExternalEvent= (4,)
Status= (5,)
ParentSynchron= 6
classScriptTaskConfigObject.ScriptTaskConfigObjectMarker
Bases: object

Every ScriptObject instance will be extended with this method.

Version added:
3.5.10.0

propertyis_task_configuration
Gets a value indicating whether this instance is a task configuration object.

Return type:
bool

Returns:
True if this instance is task config object; otherwise, False.

classScriptTaskConfigObject.ScriptTaskObjectMarker
Bases: object

Every ScriptObject instance will be extended with this method.

Version added:
3.5.10.0

propertyis_task
Gets a value indicating whether this instance is a task object.

Return type:
bool

Returns:
True if this instance is task object; otherwise, False

classScriptTaskConfigObject.ScriptTaskConfigObject
Bases: ScriptTaskConfigObjectMarker

Functionality for manipulating task configuration objects.

Version added:
3.5.10.0

create_task(name)
Add a task object to a task configuration.

Return type:
ScriptTaskObject

classScriptTaskConfigObject.ScriptTaskObject
Bases: ScriptTaskObjectMarker

Functionality for manipulating task objects.

Version added:
3.5.10.0

propertyname
Name of the task.

Return type:
str

 propertykind_of_task
Kind of task.

Return type:
KindOfTask

 propertyevent_pou_guid
Guid of POU for event.

Return type:
Guid

 propertypriority
Priority of the task.

Return type:
str

 propertyinterval
Interval of the task.

Requires the property kind_of_task to be set to KindOfTask.Cyclic or KindOfTask.ExternalEvent if the device supports it.

Return type:
str

 propertyinterval_unit
Unit used for the interval.

Requires the property kind_of_task to be set to KindOfTask.Cyclic or KindOfTask.ExternalEvent if the device supports it.

Return type:
str

 propertywatchdog
Settings for the watchdog of the task.

Return type:
ScriptWatchdog

 propertyevent
Use event to trigger the task.

Requires the property kind_of_task to be set to KindOfTask.Event or KindOfTask.Status.

Return type:
str

 propertyexternal_event
Use external event to trigger the task.

Requires the property kind_of_task to be set to KindOfTask.ExternalEvent.

Return type:
str

 propertycore_binding
Core binding. On multicore deivce each task can have an optional core binding.

Return type:
int

 propertyparent_synchron_task
Task of the device application which allows synchronous calls to child application in bus cycle.

Requires the property kind_of_task to be set to KindOfTask.ParentSynchron.

Return type:
str

 propertypous
Collection of POUs which are executed by the task.

Return type:
ScriptPouObjectCollection

classScriptTaskConfigObject.ScriptWatchdog
Bases: object

A configuration for a watchdog.

Version added:
3.5.10.0

propertyenabled
Enable the watchdog for a task.

Return type:
bool

 propertytime
Time monitoring for a task.

Return type:
str

 propertytime_unit
Unit user for the time.

Return type:
str

 propertysensitivity
Sensitivity of the watchdog.

Return type:
str

classScriptTaskConfigObject.ScriptPouObjectCollection(iterable=(), /)
Bases: list

A collection of POUs which are executed by a task.

Version added:
3.5.10.0

add(pou_name, comment=None)
Add a POU to the list.

Parameters:
pou_name (str) – Name of the POU.

comment (str) – Optional comment about this entry

insert(index, pou_name, comment)
Insert a POU to the list at the specified index.

Parameters:
index (int) – Index of a POU at which a new POU should be inserted.

pou_name (str) – Name of the POU.

comment (str) – Optional comment about this entry

replace(index, pou_name, comment)
Replace the POU in the list at the specified index.

Parameters:
index (int) – Index of a POU which should be replaced.

pou_name (str) – Name of the POU.

comment (str) – Optional comment about this entry

remove(index_or_name)
Remove a POU from the list at the specified index OR: Remove the first POU with the specified name from the list.

Parameters:
index_or_name (int or str) – Index or name of a POU which should be removed.

ScriptTreeObject
classScriptTreeObject.ScriptTreeObject
Bases: object

Common base functionality for ScriptObject and ScriptProject.

propertyproject
Gets the project.

This returns “this” rsp. “self” if called on Projects.

Return type:
ScriptProject

 propertyhandle
Gets the internal Automation Platform handle of the Project.

This handle is primarily useful for other Atomation Platform plugins which provide functionality for scripts via ScriptDriver. When they consume ScriptProject as their parameters, they can use the handle to gain access to the underlying Automation Platform object.

Return type:
int

find(name, recursive=False)
Finds objects matching the given name.

Names are not unique in the tree, so several Objects can be delivered. The search is against the nonlocalized name.

Parameters:
name (str) – The Name.

recursive (bool) – Whether we search recursively.

Return type:
list[ScriptObject]

Returns:
The collection of objects.

get_children(recursive=False)
Gets the children of our object.

Parameters:
recursive (bool) – If set to True, we work recursively.

Return type:
list[ScriptObject]

Returns:
All child objects.

propertyis_root
Gets a value indicating whether this instance is the root of the object tree.

This returns true for all ScriptProject instances, and false for all ScriptObject instances.

Return type:
bool

ScriptDeviceRepository
classScriptDeviceRepository.ScriptDeviceRepository
Bases: object

Device respository.

propertysources
Get the repository sources of the device repository.

Return type:
ScriptRepositorySourceList

create_device_identification(type, id, version)
Factory method for a DeviceId object.

Parameters:
type (int) – The device type.

id (str) – The device id.

Return type:
str

Returns:
A new DeviceId object with the provided values.

create_module_identification(type, id, version, module_id)
Factory method for a ModuleId object.

Parameters:
type (int) – The device type.

id (str) – The device id.

module_id (str) – The module id.

Return type:
str

Returns:
A new ModuleId object with the provided values.

import_device(path: str, source: ScriptRepositorySource, converter_factory_guid: Guid, save_device_cache: bool = True)
Import a device description file into a repository.

Warning

The original C# function that is called with this method contains 3 overloads. It is strongly advised to pass all arguments with their respective keywords. stream, path, and source_path are not actually optional, they just aren’t required in every overload. Pass them if your overload needs them!

Convert a foreign device description file and import the result into a repository.

List of known converter factories:¶
{C633F245-876F-45E8-AAB4-3FBD994C08B8}

Use as default because all available converters are tried

{3992C588-7BDB-4A7C-908D-F444808D8CD2}

XML files of EtherCAT

{6066AEF4-F19A-41ac-A249-721BDAE32D40}

GSDML files of Profinet IO

{CDDE0374-9EFD-401e-93C8-F19443FB60ED}

XML files of Sercos3

{1ce4a9c1-37d3-496c-9e80-cd99ad3807ee}

EDS files of CANbus

Parameters:
path (str) – The file that contains the device description. This must be a valid device description file. Other types of device descriptions must be imported by special plug-ins.

source (ScriptRepositorySource) – The repository source where the device should be stored. This parameter may be None, in which case the default repository source is used. The repository source must be one of the sources defined in sources.

converter_factory_guid (str) – The guid of the converter to import a foreign device description. For example CANopen EDS files.

save_device_cache (bool) – If True, after removing the device the device cache is also written. If False, the device cache is not written. If many devices are removed, this is much faster.

Return type:
DeviceId

Returns:
The ID of the imported device description.

import_vendor_description(path: str, source: ScriptRepositorySource)
Import a device description file into a repository.

Warning

The original C# function that is called with this method contains 2 overloads. It is strongly advised to pass all arguments with their respective keywords. stream, path, and source_path are not actually optional, they just aren’t required in every overload. Pass them if your overload needs them!

import_vendor_description(path, source) (2/2)

Parameters:
path (str) – The file that contains the vendor description. This must be a valid vendor description file.

source (ScriptRepositorySource) – The repository source where the device should be stored. This parameter may be None, in which case the default repository source is used. The repository source must be one of the sources defined in sources.

Return type:
ScriptVendorDescription

Returns:
The imported vendor description.

remove_device(device_id, source, save_device_cache=True)
Remove a device from the specified repository source.

Parameters:
device_id (DeviceId) – Defines the device to remove.

source (ScriptRepositorySource) – Remove the device from this repository source. If None the device is removed from the default repository source.

save_device_cache (bool) – If True, after removing the device the device cache is also written. If False, the device cache is not written. If many devices are removed, this is much faster.

remove_vendor_description(vendor_id, source)
Remove a vendor description from the specified repository source.

Parameters:
vendor_id (int) – The vendor id.

source (ScriptRepositorySource) – Remove the device from this repository source. If None the device is removed from the default repository source.

save_device_cache()
Saves the current devices in the device cache. Could be used to force it after adding or removing many devices.

rebuild_device_cache()
Rebuild the device cache.

The device cache is deleted, initialized and saved.

get_device_category(category: Guid)
This overload is called when category_id is of type int.

Get the device category with the specified type GUID.

Parameters:
category_id (Guid) – The type GUID of the device category implementation.

Return type:
ScriptDeviceCategory

Returns:
The requested device category, or None if the device category does not exist.

get_device_family(family)
Device family.

Parameters:
family (str) – VendorID:FamilyID.

Return type:
ScriptDeviceFamily

get_all_devices(name: str, source: ScriptRepositorySource)
Get a collection containing all devices in the repository.

Warning

The original C# function that is called with this method contains 5 overloads. It is strongly advised to pass all arguments with their respective keywords.

Get all device which contain the specified name.

Parameters:
name (str) – Text which the name of the device has to contain.

source (ScriptRepositorySource) – If not None, only this repository source will be searched.

Return type:
tuple

Returns:
A device tuple containing the current result of the query.

get_device(device_id)
Get the device description with the specified device identification.

Parameters:
device_id (DeviceId) – Device identification.

Return type:
ScriptDeviceDescription

Returns:
The requested device description, or None if the device description does not exist.

get_all_vendor_descriptions(source: ScriptRepositorySource)
Get a collection of all vendor descriptions in the repository.

Warning

The original C# function that is called with this method contains 2 overloads. It is strongly advised to pass all arguments with their respective keywords.

Get the vendor description with the specified vendor Id.

Parameters:
source (ScriptRepositorySource) – Repository source.

Return type:
tuple[ScriptVendorDescription]

Returns:
A collection of vendor descriptions containing the current result of the query.

get_vendor_description(vendor_id)
Get the vendor description with the specified vendor Id.

Parameters:
vendor_id (int) – Vendor Id.

Return type:
ScriptVendorDescription

Returns:
The requested vendor description, or None if the vendor description does not exist.

classScriptDeviceRepository.ScriptRepositorySourceList(iterable=(), /)
Bases: list

A collection of ScriptRepositorySource objects.

add(name, location_url)
Add a new repository source with the specified name.

Parameters:
name (str) – Name for the new source.

Return type:
ScriptRepositorySource

Returns:
The added repository source.

remove(source)
Remove an existing repository source.

Internal sources cannot be removed.

Parameters:
source (ScriptRepositorySource) – The repository source to remove.

move(source, index)
Move an existing repository source to the specified location in the collection.

Parameters:
source (ScriptRepositorySource) – Existing repository source.

index (int) – New index of the repository source.

classScriptDeviceRepository.ScriptRepositorySource
Bases: object

Repository source.

propertyname
Get or set the name of the repository source.

Return type:
str

 propertylocation_url
Get or set the location URL.

Return type:
str

 propertyis_internal
Return whether the repository source is internal.

If true, then this repository source is an implicit source (like the project internal repository or the installation specific repository). Therefore its properties like name and location are readonly and may not be changed.

Return type:
bool

classScriptDeviceRepository.ScriptDeviceCategory
Bases: object

Category of devices.

Devices can be grouped into categories by means of the DeviceDescription/Device/DeviceInfo/Category tags of the device description file. One can implement a corresponding class of this interface to display these types in a user-friendly way.

propertycategory_id
Id of the category.

Return type:
int

 propertyparent_category
The type GUID of the parent device category implementation, or Guid.Empty, if this device implementation is top-level.

Return type:
Guid

 propertyname
Gets a user-friendly display name for this device category.

This string should be localized.

Return type:
str

 propertydescription
Gets a user-friendly description for this device category.

This string should be localized.

Return type:
str