ScriptCasEdgeGatewayManager

class ScriptCasEdgeGatewayManager.CasEdgeInfo

Bases: object

Information about an edge gateway on the server

property name: str

The name of the edge gateway, as configured in the server.

property id: int

The ID of the edge gateway on the server.

property cert_thumbprint: str

The primary certificate thumbprint used by the server to verify the connection to the edge gateway.

property secondary_cert

The secondary certificate thumbprint, or None if not present.

Return type:

str | None

Note

When a certificate is refreshed before it expires, there is a small time frame when both the old and the new certificate are valid. In this case, this property stores the new certificate.

property description

The description of the edge gateway on the server, if the user configured one.

Return type:

str | None

class ScriptCasEdgeGatewayManager.CasEdgeGatewayManager

Bases: object

Methods and properties to investigate and configure an edge gateway for the CODESYS Automation Server.

Note

Being familiar with the “Configure Edge Gateway” view in either CODESYS or the Service Tool will help understanding this API. See https://help.codesys.com/webapp/_casc_cmd_connect_edge_gateway;product=codesys_automation_server;version=1.19.0.0#view-connect-or-reconfigure-edge-gateways for more information.

Note

Depending on the state, all properties may return None if no data available at the moment.

Note

Only available if the “CODESYS Automation Server Connector” Plugin and the “CODESYS Script Engine” packages are installed!

property edge_error_message: str

Any error messages (human-readable) regarding the edge configuration.

Return type:

str

property edge_gateway_address: str

The IP address or DNS host name of the edge gateway.

Return type:

str

property edge_gateway_port: int

The TCP port of the edge gateway, or None if not initialized yet.

Return type:

int

property edge_server_url: str

The server url configured for the edge gateway, or None if nothing is set yet.

Return type:

str

property edge_config_mode: bool

Edge configuration can only be written if this property returns <c>True</c>. For security reasons, the configuration mode has to be explicitly enabled on the edge gateway, e. G. via the SysTray menu for Windows, the installer package, or by manually editing the gateway configuration file and restarting the gateway.

Return type:

bool

property edge_communication_state: bool

Reflects whether the edge communication plugin is enabled in the edge gateway. If it is disabled, the edge gateway will not connect to the server, but the configuration will be retained.

Return type:

bool

property edge_cert_info: str

Information about the current certificate used by the edge gateway to connect to the server.

Return type:

str

Note

The “scenario” id for the certificate store is “CmpEdgeGateway”.

property edge_cert_problems: str

Human readable description of any problems identified with the edge gateway certificate. Is None or empty if no problems were detected.

Return type:

str

property edge_cert_thumbprint: str

The thumb print of the current certificate used by the edge gateway to connect to the server.

Return type:

str

property edge_device_name: str

The device name announced by the edge gateway.

Return type:

str

property edge_vendor_name: str

The vendor name announced by the edge gateway.

Return type:

str

property edge_version_info: str

The version information announced by the edge gateway, human readable formatted.

Return type:

str

Note

This contains both edge_version and edge_core_version

property edge_version: Version

The product / firmware version announced by the edge gateway.

Return type:

Version

Note

This version is freely assigned by the device vendor, and may differ from the edge_core_version.

property edge_core_version: Version

The core version of the edge gateway component built into the edge gateway.

Return type:

Version

property edge_node_name: str

The node name announced by the edge gateway.

Return type:

str

property edge_target_info: str

The target id and device type information (human readable).

Return type:

str

Note

This contains both edge_device_type and edge_target_id.

property edge_device_type: CasDeviceType

The device type of the edge gateway. This is usually CasDeviceType.Communication for standalone gateways, and CasDeviceType.Programmable for runtimes with builtin edge gateway functionality.

Return type:

CasDeviceType

property edge_target_id: int

The target id of the gateway.

This is 32 bit, the upper 16 bits are Vendor ID, lower 16 bits are Device ID.

Return type:

int

property edge_proxy_url: str

The proxy url configured for the edge gateway, or None if no proxy is set.

Return type:

str

property edge_proxy_user: str

The proxy auth username configured for the edge gateway, or None if no proxy user is set.

Return type:

str

property edge_proxy_password: str

The proxy auth password configured for the edge gateway, or None if no proxy password is set.

Return type:

str

property server_checked_url: str

The server url we checked, either implicitly with check_edge_gateway when a server is already configured, or explicitly with check_server().

Return type:

str

property server_known_edge_gateways: list[ScriptCasEdgeGatewayManager.CasEdgeInfo]

Contains the list of known edge gateways in the server, or an empty list if no edge gateways are known.

Return type:

list[CasEdgeInfo]

property server_edge_match: CasEdgeInfo

The information about the edge gateway entry on the server matching the configuration of the edge gateway, this is filled by check_edge_gateway when executed on an already configured edge gateway.

Return type:

CasEdgeInfo

property server_cert_info: str

Human-readable state about the certificate, e. G. whether edge_cert_thumbprint matches CasEdgeInfo.cert_thumbprint or CasEdgeInfo.secondary_cert.

Return type:

str

property server_cert_error: str

Any information about errors with the certificate (or configuration) on the server side, for example, when the certificate thumbprints known to the server do not match the certificate configured on the edge gateway.

Return type:

str

property server_check_error: str

Any errors which occurred when the server was checked.

Return type:

str

property possible_actions: CasEdgeConfigActions

Flags bitfield of possible actions for the CasEdgeGatewayManager. Which operations are allowed depends on the current state, any other operations will most likely throw exceptions.

Return type:

CasEdgeConfigActions

check_edge_gateway(gateway: str, port: int = 1217, verify_server: bool = True)

Connects to the specified edge gateway, and checks its state, setting/refreshing the properties of this class.

Parameters:

  • gateway (str) – The IP address or DNS host name of the Edge Gateway.

  • port (int) – The TCP port, default is 1217.

  • verify_server (bool) – Set this to <c>False</c> to disable server lookups (implicit check_server(...)) of already configured edge gateways.

Note

If verify_server==True, and the edge gateway already has a valid server connection configured, this method will also try to connect to the server and verify against the information stored there.

check_server(server_url)
Checks the specified Server and refreshes the list of

available edge gateways server_known_edge_gateways.

Parameters:

server_url (str | Uri) – The server URL or hostname.

connect_to_server(server_url, name: str, description: str = '', proxy_url=None, proxy_user: Optional[str] = None, proxy_password: Optional[str] = None)

Connects the current edge gateway to the automation server.

May be called after``check_edge_gateway()`` was executed successfully on a not-yet configured edge gateway, and edge_config_mode==True;

Parameters:

  • server_url (str | Uri) – The url or hostname of the automation server the edge gateway should be connected to.

  • name (str) – The name the edge gateway should have on the server.

  • description (str) – Optional description of the gateway on the server.

  • proxy_url (str | Uri | None) – Proxy url if the edge gateway needs to connect through an explicit proxy to the server.

  • proxy_user (str | None) – Proxy user if the proxy at proxy_url needs authentication.

  • proxy_password (str | None) – Proxy password if the proxy at proxy_url needs authentication.

replace_edge_gateway(edge_info, proxy_url=None, proxy_user: Optional[str] = None, proxy_password: Optional[str] = None)

Connects the current edge gateway to the current automation server, taking the role of an already existing gateway. May be called after check_edge_gateway was executed successfully on a not-yet configured edge gateway, and edge_config_mode==True, and additionally, server_known_edge_gateways must have been refreshed via check_server().

May be called after``check_edge_gateway()`` was executed successfully on a not-yet configured edge gateway, and edge_config_mode==True;

Parameters:

  • edge_info (int | CasEdgeInfo) – Either the numeric ID of the edge gateway on the server, or an CasEdgeInfo entry from the server_known_edge_gateways property.

  • proxy_url (str | Uri | None) – Proxy url if the edge gateway needs to connect through an explicit proxy to the server.

  • proxy_user (str | None) – Proxy user if the proxy at proxy_url needs authentication.

  • proxy_password (str | None) – Proxy password if the proxy at proxy_url needs authentication.

renew_certificate()

Renews and replaces the certificate currently used to authenticate the edge gateway to the server.

Note

This method may be used to repair a connection when the edge gateway has been offline for too long, so the automatic certificate renewal was not performed. (Usually, this means the edge gateway has been offline for longer than 3 months.)

disable_communication()

Disables the edge communication to the server by setting the edge_communication_state setting to 0, but keeps the configuration intact.

Note

Communication can be re-enabled later using enable_communication().

enable_communication()

Re-activates the edge communication to the server by setting the edge_communication_state setting to 1, this requires a correct configuration.

repair_reconnect(proxy_url=None, proxy_user: Optional[str] = None, proxy_password: Optional[str] = None)

Reconnects the specified edge gateway to the already configured automation server, updating the proxy configuration.

This will repair mismatching certificates etc. To be called on an already configured edge gateway with activated config mode.

Parameters:

  • proxy_url (str | Uri | None) – Proxy url if the edge gateway needs to connect through an explicit proxy to the server.

  • proxy_user (str | None) – Proxy user if the proxy at proxy_url needs authentication.

  • proxy_password (str | None) – Proxy password if the proxy at proxy_url needs authentication.

change_proxy_settings(proxy_url=None, proxy_user: Optional[str] = None, proxy_password: Optional[str] = None, disable_config_mode: bool = True)

Sets, updates or deletes the proxy configuration.

To be called on an already configured edge gateway with activated config mode.

Parameters:

  • proxy_url (str | Uri | None) – Proxy url if the edge gateway needs to connect through an explicit proxy to the server.

  • proxy_user (str | None) – Proxy user if the proxy at proxy_url needs authentication.

  • proxy_password (str | None) – Proxy password if the proxy at proxy_url needs authentication.

  • disable_config_mode (bool) – If this is set to False, the config mode is not implicitly disabled after this operation.

disconnect()

Disconnects the current edge gateway from the automation server, and deletes the configuration.

Note

This operation will only affect the edge gateway configuration, but not delete the edge gateway entry on the server.

disable_config_mode()

Just disables the config mode on this edge gateway.

craft_edge_webapp_url(info: Optional[CasEdgeInfo] = None, start_scan: bool = False) → str

Crafts the URL of the edge gateway within the CAS WebApp.

Parameters:

  • info (CasEdgeInfo | None) – The edge to craft the URL for, or None to use server_edge_match.

  • start_scan (bool) – If set to True, the url is for the network scan page of the gateway, instead of the normal page.

open_edge_webapp_url(info: Optional[CasEdgeInfo] = None, start_scan: bool = False)

Opens the URL of the given edge gateway in the system default browser.

Parameters:

  • info (CasEdgeInfo | None) – The edge to open in the browser, or None to use server_edge_match.

  • start_scan (bool) – If set to True, the url is for the network scan page of the gateway, instead of the normal page.