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:

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

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

oOtherwise, 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:

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)
# 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)