Einführung in die EcoStruxure Machine Expert Python-API (mit dir() und inspectapi )

Übersicht

EcoStruxure Machine Expert stellt eine Python-API zur Verfügung, die Sie für EcoStruxure Machine Expert-Skripte verwenden können. Zum Schreiben von Python-Skripten brauchen Sie meist nur die Namen von Funktionen oder eine Liste der erforderlichen Parameter und ihrer Namen. Oft benötigen Sie auch die verfügbaren Funktionen eines Objekts, das von einer aufgerufenen API-Funktion zurückgegeben wird. Die Funktionen sind hilfreich für die Verwendung der EcoStruxure Machine Expert Python-API und die Entwicklung von Python-Skripten.

Integrierte dir(…)-Funktion von Python

Ohne Argumente gibt diese Funktion die Liste der Namen im aktuellen lokalen Bereich aus. Mit einem Argument versucht diese Funktion, eine Liste gültiger Attribute für das Objekt auszugeben.

Der dir()-Standardmechanismus von Python verhält sich für verschiedene Objekttypen anders, da er versucht, die relevantesten anstatt aller Informationen auszugeben:

  • Wenn das Objekt ein Modulobjekt ist, enthält die Liste die Namen der Attribute des Moduls.

  • Wenn das Objekt ein Typ- oder Klassenobjekt ist, enthält die Liste die Namen der Attribute und rekursiv der Attribute seiner Basisklassen.

  • Andernfalls enthält die Liste die Namen der Attribute des Objekts, die Namen der Attribute seiner Klasse und rekursiv der Attribute der Basisklassen.

Beispiel (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-Funktionen

Da die dir()-Funktion nicht alle Elemente der EcoStruxure Machine Expert Python-API aufführt, werden zusätzliche Funktionen bereitgestellt, um die fehlenden Elemente für die Python-Skriptentwickler anzuzeigen.

inspectapi ist ein Python-Modul, das automatisch geladen wird, wenn LogicBuilderShell.exe oder die Ansicht Scripting Immediate gestartet wird. Deshalb ist eine Variable bzw. ein Modul vom Typ inspectapi im aktuellen Bereich verfügbar. Diese Variable wird auch aufgeführt, wenn Sie die Funktion dir() ausführen.

Die Variable bzw. das Modul vom Typ inspectapi bietet die folgenden Funktionen:

Funktionsname

Parameter

Beschreibung

inspectapi.dir

obj: Geben Sie ein Objekt (z. B. eine Variable) an, zu dem Sie weitere Informationen erhalten möchten.

(optional) verbose: Der Standardwert ist FALSE. Setzen Sie den Parameter auf TRUE, um einen verbosen Ausgang zu erhalten.

Diese Funktion stellt eine Liste verfügbarer Mitgliedsvariablen der EcoStruxure Machine Expert Python-API zur Verfügung, die Sie aufrufen können. Die Felder, Eigenschaften, Ereignisse und Methoden werden aufgeführt.

inspectapi.dir_events

Diese Funktion stellt eine Liste verfügbarer Ereignisse der EcoStruxure Machine Expert Python-API zur Verfügung, die Sie aufrufen können.

inspectapi.dir_fields

inspectapi.dir_methods

inspectapi.dir_properties

inspectapi.help

()

Mit dieser Funktion wird die Online-Hilfe des Benutzerhandbuchs der CODESYS-Skript-Engine geöffnet.

Weitere Informationen finden Sie auch hier: Benutzerhandbuch der Skript-Engine von Schneider Electric.

obj: Geben Sie ein Objekt (z. B. eine Variable) an, für das die Online-Hilfe angezeigt werden soll.

Über diese Funktion wird die Online-Hilfe des Objekts aufgerufen.

  • Wenn für das Objekt keine Dokumentation vorhanden ist, wird die Online-Hilfe für die Skript-Engine geöffnet.

  • Wenn für das Objekt mehrere Hilfethemen vorhanden sind (da Erweiterungen für das Objekt vorhanden sind oder das Objekt über mehrere dokumentierte Schnittstellen verfügt), wird ein Dialogfeld mit den entsprechenden Hilfethemen geöffnet. Doppelklicken Sie auf einen Eintrag, um das zugehörige Hilfethema zu öffnen.

  • Wenn nur ein Hilfethema für das Objekt vorhanden ist, wird das Hilfethema direkt geöffnet.

Beispiele: 

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

Ausgabe: 

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)

Ausgabe: 

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)

Ausgabe (gekürzt): 

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)

Ausgabe (gekürzt): 

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)