EcoStruxure Machine Expert 脚本 - Python API

概述

EcoStruxure Machine Expert 提供了能够用在 EcoStruxure Machine Expert 脚本中的 Python API。

Python API 包含两种类别：

  • 标准 Python API 和 Python 模块/包

  • EcoStruxure Machine Expert Python API

标准 Python API（用于处理字符串、数组、文件等）是 EcoStruxure Machine Expert 安装的一部分。如需获得详细的帮助，请上网查询（比如，https://docs.python.org/3/）。您可以用可通过互联网获得的 EcoStruxure Machine Expert 模块和包来扩展 Python 安装。

为了自动执行 EcoStruxure Machine Expert，在 EcoStruxure Machine Expert 安装中还包括了 EcoStruxure Machine Expert Python API。它用于比如打开或关闭项目、更改项目内容、或者编译项目并将其下载到控制器。

EcoStruxure Machine Expert Python API 概念在本章节进行了介绍。另请参阅脚本引擎示例。如要详细了解 EcoStruxure Machine Expert Python API，请参阅章节深入利用 EcoStruxure Machine Expert API。

有关详细的方法/功能描述或参数描述，请参阅 EcoStruxure Machine Expert 在线帮助软件部分的脚本引擎一节。

基于面向对象编程的 EcoStruxure Machine ExpertPython API 概念

如要获得适合您 Python 脚本的 API 方法，必须熟悉 EcoStruxure Machine Expert Python API 概念以及如何将 API 集成到脚本引擎（脚本执行）中。EcoStruxure Machine Expert Python API 背后的主要概念是面向对象的 API 法。面向对象编程 (OOP) 是一种基于两种概念（对象和代码）的编程范式。对象是包含数据的数据结构，为字段形式，又称为属性。代码为过程的形式，又称为方法。对象的过程可以访问和修改对象的与这些过程相关联的数据字段。根据 OOP 设计的计算机程序由彼此交互的对象组成。

编写脚本时的一大挑战是，要将详细的 EcoStruxure Machine Expert Python API 文档映射到正确对象上以调用过程。

预定义变量和类型

在运行脚本或使用 REPL 时（在 LogicBuilderShell.exe 或 Scripting Immediate 视图中），您拥有一个包含预定义变量（和类型）的主脚本范围。您可以将它们用在脚本中，作为 EcoStruxure Machine Expert Python API 的输入条目。如要列出主脚本范围中可用的预定义变量，请启动 LogicBuilderShell.exe 并执行 dir()。

通过运行 dir() 获得的预定义变量列表： 

>>> dir()
['AccessRight', 'ApplicationState', 'ArchiveCategories', 'ChannelType', 'Compile
rMessage', 'ConflictResolve', 'ConnectorRole', 'CredentialSourceKind', 'DeviceID
', 'DeviceUserManagementFlags', 'DiagType', 'ExportReporter', 'Guid', 'Implement
ationLanguage', 'ImportReporter', 'MultipleChoiceSelector', 'NativeExportReporte
r', 'NativeImportFilter', 'NativeImportHandler', 'NativeImportResolve', 'NativeI
mportResult', 'ObjectPermissionKind', 'OnlineChangeOption', 'OperatingState', 'P
ermissionState', 'ProjectType', 'PromptChoice', 'PromptChoiceFilter', 'PromptHan
dling', 'PromptResult', 'ResetOption', 'SV_DEV', 'SV_POU', 'Severity', 'TimeoutE
xception', 'ValuesFailedException', 'Version', '__SoMachine__', '__builtins__',
'__doc__', '__file__', '__name__', 'communication_settings', 'compiler_settings'
, 'etest_test_provider', 'feature_settings_manager', 'librarymanager', 'libraryp
ackage_service', 'new_project', 'online', 'projects', 'system', 'visualization_s
ettings']

此列表中以小写字母书写的预定义条目是引用了提供方法或字段的对象的变量。这是一种能够在加载有或未加载 EcoStruxure Machine Expert 项目的情况下工作的全局 API。

比如，system 或 projects 或 online。

  • system：集成到 EcoStruxure Machine Expert 中时所使用的功能。此对象提供了 ISystemInterface 中所述的功能，例如，从 EcoStruxure Machine Expert 访问消息视图，或者使用 ui_present 验证程序是否正在 --noUI 模式下运行。

  • projects：用于项目管理的功能。此对象提供 IScriptProjects Interface 中所述的功能，例如，加载项目和项目存档。并且，它还是各项目的入口点。

  • online：在线访问控制器时所使用的功能。您可以使用 create_online_application 方法来为应用程序对象检索特定在线对象（IScriptOnlineApplication 中所述）。此对象让您能够登录到控制器、启动应用程序、以及读取变量值。

有关详细信息，请参阅 EcoStruxure Machine Expert 在线帮助中的脚本引擎插件 API 引用部分。

此列表中以大写字母开头的预定义条目是可在 Python 脚本中使用或实例化的枚举或类型/类。比如，DeviceID（类）或 Guid（类）或 PromptChoice（枚举）。

在 EcoStruxure Machine Expert 树结构中搜索和导航

EcoStruxure Machine Expert 项目由组织成对象树形式的设备、POU、DUT、GVL 等组成（请参见比如 Logic Builder 中的设备树）。此对象树（项目树）附加到 projects.primary。在 projects.primary 中，API 让您能够使用 find(…) 方法搜索对象。您可以通过比如使用 get_children() 方法获取直接子对象（比尔，控制器设备）的方式，在项目树中导航。在每个子对象上，您可以再次调用 get_children() 来获取其直接子对象，以此类推。

注： 项目树对象中可用的方法因对象而异，具体取决于对象的类型（POU、DUT、GVL、设备）。最好是使用 inspectapi.dir(…) 来查看对象上可用 API 方法的列表。

示例

使用全局 API 函数打开项目（示例）： 

projects.open("MyProject.project")

查找并重命名项目树对象（示例）（项目加载后）： 

myObject = projects.primary.find("SERCOSIII")[0]
myObject.rename("New_SERCOSIII_Name")

图中显示了用户界面中的项目树对象以及通过脚本打印的遍历项目树：

遍历项目树（如上所打印）的脚本示例： 

def print_tree_of_obj(treeobj, depth=0, verbose=False):
    name = treeobj.get_name(False)   
    if treeobj.is_device:
        deviceid = treeobj.get_device_identification()
        details = ""
        if verbose == True:
            details = " [Device {0}/{1}/{2}]".format(deviceid.type, deviceid.id, deviceid.version)
        print("{0} * {1}{2}".format("   "*depth, name, details))
    else:
        print("{0} * {1}".format("   "*depth, name))
   
    for child in treeobj.get_children(False):
        print_tree_of_obj(child, depth+1, verbose)
def print_tree_of_project(pro, verbose=False):
    if pro == None:
        print("No project open.")
    else:
        for obj in pro.get_children():
            print_tree_of_obj(obj, 0, verbose)
def print_tree(verbose=False):
    if projects.primary != None:
        print_tree_of_project(projects.primary, verbose)
    else:
        print("No project open.")
print_tree(True)