scriptDoc.txt•236 kB
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 ‘<’ character, it is regarded as an XML file. Rationale: On windows, < is an invalid char in path names, and it is contained in every XML file. (On other common platforms like unix and OSX, < 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 ‘<’ character, it is regarded as an XML file. Rationale: On windows, < 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