Explore EcoStruxure Machine Expert Python API (with dir() and inspectapi)

Overview

EcoStruxure Machine Expert provides a Python API that you can use for EcoStruxure Machine Expert scripting. When you write Python scripts, most times you only need names of functions or the list of required parameters and its names. You often also need the available functions of an object returned by an API function you have called. The following functions allow you to explore the EcoStruxure Machine Expert Python API to support you in developing Python scripts.

Built-in dir(…) function of Python

Without arguments, this function returns the list of names in the current local scope. With an argument, this function attempts to return a list of valid attributes for that object.

The default dir() mechanism of Python behaves differently with different types of objects, as it attempts to produce the most relevant, rather than complete information:

  • If the object is a module object, the list contains the names of the attributes of the module.

  • If the object is a type or class object, the list contains the names of its attributes, and recursively of the attributes of its bases.

  • Otherwise, the list contains the names of the attributes of the object, the names of the attributes of its class, and recursively of the attributes of the base classes.

Example (in LogicBuilderShell.exe): 

>>> import struct
>>> dir()   # show the names in the module namespace
['__builtins__', '__doc__', '__name__', 'struct']
>>> dir(struct)   # show the names in the struct module
['Struct', '__builtins__', '__doc__', '__file__', '__name__',
 '__package__', '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
 'unpack', 'unpack_from']
>>> class Shape(object):
        def __dir__(self):
            return ['area', 'perimeter', 'location']
>>> s = Shape()
>>> dir(s)
['area', 'perimeter', 'location']

inspectapi Functions

Since the dir() function does not list all EcoStruxure Machine Expert Python API elements, additional functions are provided to display them for Python script developers.

inspectapi is a Python module loaded automatically while starting the LogicBuilderShell.exe or the Scripting Immediate view. As a result, a variable/module inspectapi is available in the current scope. This variable is also listed by executing the dir() function.

The inspectapi variable/module provides the following functions:

Function name

Parameters

Description

inspectapi.dir

obj: Specify an object (for example, a variable) for which you get more information.

(optional) verbose: The default value is FALSE. Set the parameter to TRUE to get verbose output.

This function provides a list of available EcoStruxure Machine Expert Python API members you can call. The fields, properties, events, and methods are listed.

inspectapi.dir_events

This function provides a list of available EcoStruxure Machine Expert Python API events you can call.

inspectapi.dir_fields

inspectapi.dir_methods

inspectapi.dir_properties

inspectapi.help

()

This function opens the online help of the CODESYS Script Engine User Guide.

For further information, also refer to the Schneider Electric Script Engine User Guide.

obj: Specify an object (for example, a variable) for which the online help will be displayed.

This function opens the online help of the object.

  • If there is no documentation for the object, the online help for the scripting engine opens.

  • If there are multiple help topics for the object (because there are extensions for the object or the object has multiple documented interfaces), a dialog box opens listing the relevant help topics. Double-click an entry to open the corresponding help topic.

  • If there is only one help topic for the object, the help topic opens directly.

Examples: 

# To see the API of the inspect api itself
inspectapi.dir(inspectapi)

Output: 

Members of type 'InspectAPI'
Methods:
  dir (obj, verbose = False)
  dir_events (obj, verbose = False)
  dir_fields (obj, verbose = False)
  dir_methods (obj, verbose = False)
  dir_properties (obj, verbose = False)
  help (obj = null)
# To see the API of projects variable
inspectapi.dir(projects)

Output: 

Members of type 'ScriptProjects'
Properties:
  [get] all
  [get] primary
Methods:
  convert (stPath, stOutputPath, converter, bPrimary)
  convert (stPath, stOutputPath, converterGuid, bPrimary)
  create (stPath, bPrimary)
  get_all ()
  get_by_path (stPath)
  get_primary ()
  open (stPath, stPassword, bPrimary)
  open (stPath, encryption_password, session_user, session_password, bPrimary)
  open_archive (stArchiveFile, stProjectPath, bOverwrite, stPassword)
  open_archive (stArchiveFile, stProjectPath, bOverwrite, encryption_password, session_user, session_password)
# open a project
proj = projects.open("c:\\temp\\MyScript.py ")
# To see API of primary project
inspectapi.dir(projects.primary)

Output (truncated): 

Members of type 'ScriptProject'
Properties:
  [set] active_application
  [get] dirty
  [get] handle
  [get] has_library_manager
  [get] has_project_info
  [get] is_root
  [get] library
  [get] path
  [get] primary
  [get] project
  [get] svn
  [get] user_management
Methods:
  add (stName, id, stModuleId)
  add (stName, iType, stId, stVersion, stModuleId)
  check_all_pool_objects ()
  clean_all ()
  close ()
  compare_to (projectFile)
  compare_to (projectFile, ignoreWhiteSpace, ignoreComments, ignoreProperties)
  ...
  logout ()
  save ()
  save_archive (stArchiveFile)
  save_archive (stPath, additional_categories)
  save_archive (stPath, comment, additional_categories)
  save_archive (stPath, additional_files, additional_categories)
  ....
  save_as (stPath, stPassword)
  save_as_compiled_library (destination_name)
  set_active_application (value)
  update ()
# search objects by name (e.g. a device with name SERCOSIII)
objs = projects.primary.find("SERCOSIII", True)
# extract object at index 0 from returned list (if found).
theObj = obj[0]
# see the available API of the found object SERCOSIII
inspectapi.dir(theObj)

Output (truncated): 

Members of type 'ScriptObject'
Properties:
  [get] connectors
  [get] device_parameters
  [get] embedded_object_types
  [get] guid
  [get] handle
  [get] has_textual_declaration
  [get] has_textual_implementation
  [get] index
  [get] is_application
  [get] is_device
  [get] is_explicit_connector
  [get] is_folder
  [get] is_libman
  [get] is_project_info
  [get] is_root
  [get] is_task
  [get] parent
  [get] project
  [get] svn
  [get] type
Methods:
  add (stName, id, stModuleId)
  add (stName, iType, stId, stVersion, stModuleId)
  allowed_interfaces_at (index)
  can_convert (targetDeviceId, targetModuleId = null)
  can_convert (targetType, targetId, targetVersion, targetModuleId = null)
  convert (targetDeviceId, targetModuleId = null)
  convert (targetType, targetId, targetVersion, targetModuleId = null)
  create_folder (stFolderName)
  disable ()
  enable ()
  export_native (destination, includeChildren, profileName, reporter)
  export_xml (reporter, stPath, bRecursive)
  export_xml (reporter, stPath, bRecursive, bExportFolderStructure)
  export_xml (reporter, stPath, bRecursive, bExportFolderStructure, bPlainText)
  export_xml (stPath, bRecursive, bExportFolderStructure, bPlainText)
  find (namePath)
  find (stName, recursive)
  get_address ()
  get_all_parameters ()
  ...
  move (newParent, nNewIndex)
  plug (stName, id, stModuleId)
  plug (stName, iType, stId, stVersion, stModuleId)
  reboot_plc ()
  remove ()
  rename (stNewName)
  reset_diagnosis_messages ()
  set_communication_address (address)
  set_gateway_and_address (stGateway, stAddress)
  set_gateway_and_address (gateway, stAddress)
  set_parameter (parameter, value)
  set_parameter_iec_address (identifier, connectorId, iecAddress)
  set_parameter_io_variable_mapping (identifier, connectorId, variable, createVariable = False)
  set_parameter_io_variable_mapping (identifier, connectorId, subElementIndex, variable, createVariable = False)
  set_simulation_mode (bSimulation)
  unplug ()
  update (id, stModuleId)
  update (iType, stId, stVersion, stModuleId)