Scripts EcoStruxure Machine Expert - API Python

Présentation

EcoStruxure Machine Expert fournit une API Python qui peut être utilisée dans des scripts EcoStruxure Machine Expert.

L'API Python API se compose de deux catégories :

API Python standard et modules/packages Python
EcoStruxure Machine ExpertPython

L'API Python standard (pour la gestion des chaînes, tableaux, fichiers, etc.) fait partie de l'installation de EcoStruxure Machine Expert. Vous trouverez une aide détaillée sur Internet (par exemple, consultez https://docs.python.org/3/). Il est possible d'étendre une installation de EcoStruxure Machine Expert avec des modules et des packages Python disponibles sur Internet.

Pour autmatiser EcoStruxure Machine Expert, une API EcoStruxure Machine ExpertePython est également comprise dans l'installation de EcoStruxure Machine Expert. Vous pouvez l'utiliser pour ouvrir ou fermer un projet, modifier le contenu d'un projet ou compiler un projet et le télécharger sur un contrôleur.

Le concept d'API EcoStruxure Machine Expert Python est décrit dans ce chapitre. Reportez-vous également aux exemples du moteur de script. Pour découvrir l'API EcoStruxure Machine Expert Python, consultez le chapitre Exploration de l'API EcoStruxure Machine Expert.

Pour plus d'informations sur les descriptions des méthodes/fonctions ou de leurs paramètres, reportez-vous à la section Scripting Engine.

Concept d'API EcoStruxure Machine ExpertPython basé sur la programmation orientée objet

Pour trouver les méthodes d'API qui conviennent à vos scripts Python, vous devez vous familiariser avec le concept d'API EcoStruxure Machine Expert Python et la manière dont l'API s'intègre au moteur de script (exécution des scripts). Le concept de base qui sous-tend l'API Python d'EcoStruxure Machine Expert est une approche orientée objet. Le paradigme de la programmation orientée objet s'appuie sur deux concepts : les objets et le code. Les objets représentent des structures contenant des données (sous la forme de champs), également appelées « attributs ». Le code se présente sous la forme de procédures, aussi appelées « méthodes ». Associées à un objet, les procédures permettent d'accéder aux champs de données de cet objet et de les modifier. Les programmes informatiques orientés objet sont constitués d'objets qui interagissent entre eux.

La principale difficulté lors de la rédaction de scripts réside dans le mappage de la documentation détaillée de l'API Python de EcoStruxure Machine Expert sur les objets appropriés pour appeler les procédures.

Variables et types prédéfinis

Lorsque vous exécutez un script ou utilisez l'environnement REPL (dans LogicBuilderShell.exe ou l'affichage Scripting Immediate), vous disposez d'un domaine principal qui prédéfinit des variables (et des types). Vous pouvez les utiliser dans votre script en tant qu'entrée dans l'API EcoStruxure Machine Expert Python. Pour dresser la liste des variables prédéfinies disponibles dans l'étendue du script principal, lancez LogicBuilderShell.exe et exécutez la commande dir().

Liste des variables prédéfinies obtenue via la commande 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']

Les variables prédéfinies en minuscules correspondent à des objets associés à des méthodes ou à des champs. C'est une sorte d'API globale qui fonctionne avec ou sans projet EcoStruxure Machine Expert chargé.

Par exemple, system ou projects ou online.

system : Fonctionnalités pour l'intégration dans EcoStruxure Machine Expert. Cet objet fournit les fonctions documentées dans ISystemInterface, notamment pour accéder à la vue Messages depuis EcoStruxure Machine Expert ou pour utiliser ui_present en vue de vérifier si le programme s'exécute en mode --noUI.
projects : Fonctionnalités de gestion de projet. Cet objet fournit les fonctions documentées dans IScriptProjects Interface, notamment pour charger des projets et des archives de projet. En outre, il constitue le point d'entrée des projets individuels.
online : Fonctionnalité pour l'accès en ligne au contrôleur. Vous pouvez utiliser la méthode create_online_application pour récupérer un objet en ligne spécifique (documenté dans IScriptOnlineApplication) pour un objet d'application. Cet objet vous permet de vous connecter à un contrôleur, de démarrer une application et de lire les valeurs de variables.

Pour plus d'informations, reportez-vous à la rubrique traitant de l'API de plug-in de moteur de script dans l'aide en ligne de EcoStruxure Machine Expert.

Les entrées prédéfinies de cette liste qui commencent par une majuscule sont des énumérations ou des types/classes que vous pouvez utiliser ou instancier dans votre script Python. Par exemple : DeviceID (classe) ou Guid (classe) ou PromptChoice (énumération).

Recherche et navigation dans la structure d'arborescence de EcoStruxure Machine Expert

Un projet EcoStruxure Machine Expert se compose de divers éléments (équipements, POU, DUT, GVL, etc.) qui sont organisés de manière arborescente (comme l'arborescence Equipements dans Logic Builder). Cette arborescence d'objets est rattachée à projects.primary. Dans projects.primary, l'API permet de rechercher des objets à l'aide de la méthode find(…). Vous pouvez naviguer dans l'arborescence de projet en utilisant notamment la méthode get_children() qui permet d'obtenir les objets immédiatement enfants (les équipements soumis à un contrôleur, par exemple). Sur chaque objet enfant, vous pouvez appeler à nouveau la méthode get_children() pour obtenir les enfants immédiats, et ainsi de suite.

NOTE : Les méthodes disponibles sur les objets de l'arborescence de projet peuvent varier d'un objet à un autre en fonction de son type (POU, DUT, GVL, équipement). Il est recommandé d'utiliser inspectapi.dir(…) pour obtenir la liste de toutes les méthodes d'API pouvant être exécutées sur un objet.

Exemples

Exemple d'utilisation d'une fonction d'API globale pour ouvrir un projet :

projects.open("MyProject.project")

Rechercher un objet dans l'arborescence de projet et le renommer (après chargement d'un projet) :

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

La figure suivante montre l'objet dans l'interface utilisateur et l'arborescence de projet traversée imprimée par un script :

Traverser l'arborescence de projet à l'aide d'un script (tel qu'imprimé ci-dessus) :

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)