class
ScriptOnline.
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.
application (ScriptObject) -- The application object to use. If this parameter is omitted, the active application is used.
Before V3.5.0.0 ScriptOnlineApplication
The online application object.
UNFORCE
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().
str
UNFORCE_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().
str
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.
3.5.3.0
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.
3.5.3.0
target (obj) -- 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.
3.5.3.0
auth_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.
3.5.3.0
CredentialSourceKind
gateways
Gets all currently known gateways.
gateway_drivers
Gets the gateway drivers.
3.5.8.0
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.
3.5.17.0
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.
3.5.17.0
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.
3.5.17.0
class
ScriptOnline.
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.
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.
is_logged_in
Gets a value indicating whether this ScriptOnlineApplication is logged in.
bool
True if is logged in; otherwise, False.
start
Starts this application.
TimeoutException -- In case of the operation taking to long.
stop
Stops this application.
TimeoutException -- In case of the operation taking to long.
application_state
Gets the application state.
ApplicationState
operation_state
Gets the operation status.
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.
ValuesFailedException -- If the write of some values fails.
force_prepared_values
Forces the prepared values.
ValuesFailedException -- If the force of some values fails.
unforce_prepared_values
Unforces the prepared values.
ValuesFailedException -- If the unforce of some values fails.
get_prepared_value
expression
Gets the prepared value for a given expression.
expression (str) -- The expression
str
The prepared value, or None if nothing is prepared.
read_value
expression
Gets the current value for a given expression.
Monitoring must be enabled.
expression (str) -- The expression.
str
The value.
read_values
*expressions
Gets the current values for a list of expressions.
Monitoring must be enabled.
expressions (list or single strings) -- The expressions.
list
The values.
get_prepared_expressions
Gets all expressions for values currently prepared for this application (including those prepared by other scripts, editors etc).
list
The prepared expressions.
get_forced_expressions
Gets all expressions for values currently forced for this application (including those prepared by other scripts, editors etc).
list
The forced expressions.
set_prepared_value
expression
value
Prepares values the specified expression.
Use None or the empty string to unprepare the value.
expression (str) -- The expression.
value (str) -- The value.
set_unforce_value
expression
restore=False
Prepares the specified forced expression for unforcing.
expression (str) -- The expression.
restore (bool) -- If set to true, the value is reset to the value before forcing.
timeout
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.
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.
3.5.0.0
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.
application
Gets the application object for this online application.
class
ScriptOnline.
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.
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.
device
Gets the underlying device object for this online device.
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.
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.
3.5.2.0
connected
Gets a value indicating whether this ScriptOnlineDevice is connected.
3.5.2.0
bool
Gets a value indicating whether this ScriptOnlineDevice or anything else has a shared connection to the device.
3.5.2.0
bool
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.
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.
3.5.2.0
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.
3.5.2.0
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.
The created user management instance.
WrongDeviceUserManagementException -- Thrown if the device only supports the live user management.
download_source
bCompact=False
*additional_items
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.
3.5.4.0
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 (list or 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.
3.5.4.0
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.
3.5.9.0
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.
3.5.9.0
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.
3.5.9.0
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.
3.5.9.0
remote_file (str) -- Path of the remote file.
create_directory
remote_directory
Create a directory on the PLC.
3.5.9.0
remote_directory (str) -- Path of the new directory.
get_file_list_of_directory
remote_directory
Read a directory on the PLC.
3.5.9.0
remote_directory (str) -- Path of the directory.
List of info elements which descript the files and directories inside the given remote directory.
rename_directory
old_name
new_name
Rename a directory on the PLC.
3.5.9.0
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.
3.5.9.0
remote_directory (str) -- Path of the remote directory.
recursive (bool) -- If True, delete the directory resursively.
activate_license
ticket
url=None
*license_names
Performs a license activation on a remote device.
The first container returned be the device will be used for activation.
3.5.10.0
ticket (str) -- The ticket which contains the licenses.
url (str) -- The license server. If None the default license server will be used.
license_names (string) -- 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.
3.5.14.0
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.
3.5.16.0
WrongDeviceUserManagementException -- Thrown if the device does not support the live user management.
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.
3.5.16.0
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.
exception
ScriptOnline.
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.
failed_expressions (list) -- The failed expressions.
failed_expressions
Gets the list of the failedexpressions.
list
class
ScriptOnline.
ScriptGateway
Bases: object
Script engine representation of a configured gateway for runtime connections.
3.5.8.0
name
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.
str
guid
Gets the unique identifier of the gateway.
3.5.8.0
Guid
gateway_driver
Gets the gateway protcol driver used for this gateway.
3.5.8.0
config_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.
3.5.8.0
obj
find_address_by_ip
address
port
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).
3.5.8.0
address (str or IPAddress) -- The IP address.
port (ushort) -- The port.
TimeoutException -- Thrown in case no device replies.
Exception -- Any other exception forwarded from the communication layer.
string
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.
3.5.8.0
Exception -- Any exceptions occurring durint the network scan.
list of ScriptScanTargetDescription
The list of devices which were found.
get_cached_network_scan_result
Gets the cached result of the last network scan on this gateway.
list of ScriptScanTargetDescription
The list of devices which were found.
class
ScriptOnline.
ScriptScanTargetDescription
Bases: object
Description of a scan target found during a device scan.
3.5.8.0
device_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".
str
type_name
Gets a string indicating the device type.
Example: "Beckhoff CX1000-100" or "BRC Motion Logic Controller".
str
vendor_name
Gets a string indicating the device vendor.
Example: "Beckhoff" or "BRC"
str
device_id
Gets the ID of the type to be matched with the installed device types (target descriptions).
DeviceID
address
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.
str
parent_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.
str
locked_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.
bool
block_driver
Property to access the type of block driver used for this target.
BlockDriverType
block_driver_address
Property to store and retrieve the driver-specific address for this target.
str
class
ScriptOnline.
ScriptGateways
Bases: list
A collection of gateways currently configured in CODESYS.
3.5.8.0
find_with_name
name
Finds all gateways with the name.
name (str) -- The name.
list of ScriptGateway
A (possibly empty) sequence of all gateways with the name.
remove_gateway
guid_or_gateway
Removes the specified gateway.
If the specified one is the default one, the next one (if any) will be the new default.
guid_or_gateway (ScriptGateway or Guid) -- The gateway to remove or its guid.
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.
name (str) -- The name.
parameters (Dict[Union(int, str, 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?) -- The gateway guid - if None is passed, a new one will be generated.
convert_gateway_parameter
parameter
paramType
Converts an object to the specified gateway parameter type.
parameter (obj) -- The parameter.
paramType (ParamType) -- Type of the parameter.
obj
The object converted to the specified ParamType.
class
ScriptOnline.
ScriptGatewayDrivers
Bases: list
Represents a list of script gateway drivers.
3.5.8.0
find_with_name
name
Finds all gateway drivers with the name.
name (str) -- The name.
list of ScriptGatewayDriver
A (possibly empty) sequence of all gateway drivers with the name.
default_driver
Gets the default gateway driver (currently bound to TCP/IP on standard CODESYS and most derivates).
class
ScriptOnline.
ScriptGatewayDriver
Bases: object
Script engine representation of a gateway driver.
3.5.8.0
guid
A Guid that uniquely identifies the driver type.
Each implementation for a gateway driver is identified by a Guid.
Guid
name
Get the user-readable name of this gateway driver.
str
gateway_parameters
Gets the gateway parameter descriptions - those are used when a new gateway with this driver is created.
A collection containing the gateway parameters.
class
ScriptOnline.
ScriptGatewayParameterDescriptions
Bases: list
A collection of script gateway parameters.
3.5.8.0
class
ScriptOnline.
ScriptGatewayParameterDescription
Bases: object
Description of parameters for a gateway driver - those are used when a new gateway with this driver is created.
3.5.8.0
id
The id of the parameter.
The id is unique for any particular gateway driver.
long
name
Human readable string, giving the name of the parameter.
str
parameter_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. |
ParamType
default_value
Default value of the parameter. May be None.
obj
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.
value (obj) -- The value to check.
Exception -- If the object is not valid.
class
ScriptOnline.
ScriptDirectoryInfo
Bases: object
Describes contents of a remote directory on the PLC.
3.5.9.0
name
Gets the name of the file/directory.
str
creation_time
Get the creation time of the file/directory.
DateTime
last_access_time
Get the last access time of the file/directory.
DateTime
last_modification_time
Get the last modification time of the file/directory.
DateTime
is_directory
Whether it is a directory.
bool
is_file
Whether it is a file.
bool
size
Get the file size in bytes.
uint
additional_dir_info
Get the additional information of the file/directory.
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.
3.5.17.0
certificate (X509Certificate2 from the .Net Framework) -- Certificate of the PLC.
chain (X509Chain from the .Net Framework) -- Chain of trust.
node_name (str) -- Name of the PLC.
bool
True, if you trust the certificate.