Création de scripts EcoStruxure Machine Expert - API Python

Présentation

EcoStruxure Machine Expert propose une API Python permettant de créer des scripts EcoStruxure Machine Expert.

Il existe deux versions de l'API Python :

oAPI Python standard et modules/packages Python

oAPI Python EcoStruxure Machine Expert

L'API Python standard (pour gérer les chaînes, tableaux, fichiers, etc.) est disponible lors de l'installation d'EcoStruxure Machine Expert. Pour obtenir une aide détaillée, consultez Internet (par exemple, le site https://docs.python.org/3/). Vous pouvez compléter votre installation EcoStruxure Machine Expert avec des packages et modules Python disponibles sur Internet.

Une API Python EcoStruxure Machine Expert, permettant d'automatiser EcoStruxure Machine Expert, est également incluse lors de l'installation d'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.

L'API Python EcoStruxure Machine Expert est décrite dans ce chapitre. Reportez-vous également aux exemples du Script Engine. Pour en savoir plus sur l'API Python EcoStruxure Machine Expert, consultez le chapitre Découvrir l'API d'EcoStruxure Machine Expert.

Pour obtenir une description des méthodes et fonctions ou de leurs paramètres, consultez la section Moteur de script de l'aide en ligne d'EcoStruxure Machine Expert, sous Logiciel.

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

Avant d'accéder aux méthodes d'API adaptées à vos scripts Python, vous devez vous familiariser avec le concept d'API Python EcoStruxure Machine Expert et comprendre comment celle-ci s'intègre dans le moteur de script (chargé de l'exécution des scripts). L'API Python EcoStruxure Machine Expert repose sur 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.

Le défi de l'écriture de scripts consiste à mettre en correspondance la documentation détaillée de l'API Python EcoStruxure Machine Expert avec les objets appropriés afin d'appeler les procédures.

Variables et types prédéfinis

Lors de l'exécution d'un script ou dans l'environnement REPL (dans LogicBuilderShell.exe ou l'affichage Scripting Immediate), des variables (et des types) sont déjà définis dans le domaine de validité principal du script. Vous pouvez les utiliser pour accéder à l'API Python EcoStruxure Machine Expert. Pour obtenir la liste des variables prédéfinies disponibles dans le domaine de validité principal du script, lancez LogicBuilderShell.exe et exécutez dir().

Liste de variables prédéfinies accessible via 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. L'API fonctionne de manière globale, avec ou sans projet EcoStruxure Machine Expert chargé.

Considérons les objets system, projects ou online.

osystem : fonctionnalité pour l'accès à EcoStruxure Machine Expert. Cet objet propose les fonctions documentées dans ISystemInterface et permet, par exemple, d'accéder à l'affichage Messages d'EcoStruxure Machine Expert, ou de vérifier via ui_present si le programme s'exécute en mode --noUI.

oprojects : fonctionnalité pour la gestion de projet. Cet objet propose les fonctions documentées dans IScriptProjects Interface et permet, par exemple, de charger des projets et des archives de projet. En outre, il constitue le point d'entrée des projets individuels.

oonline : fonctionnalité pour l'accès en ligne au contrôleur. Avec la méthode create_on­line_application, vous pouvez récupérer l'objet en ligne (documenté dans IScriptOnlineApplication) correspondant à 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, consultez la rubrique Référence à l'API de plug-in du Script Engine dans l'aide en ligne d'EcoStruxure Machine Expert.

Les entrées prédéfinies commençant par une majuscule correspondent à des énumérations ou des types/classes pouvant être utilisés ou instanciés dans le script Python. Exemples : DeviceID (classe), Guid (classe), PromptChoice (énumération).

Recherche et navigation dans l'arborescence d'EcoStruxure Machine Expert

Un projet EcoStruxure Machine Expert se compose de divers objets (équipements, POU, DUT, GVL, etc.) organisés sous la forme d'une arborescence (arborescence Équipements de Logic Builder, par exemple). Cette arborescence d'objets (l'arborescence du projet) est associée à projects.primary. L'API permet de rechercher des objets dans projects.primary via la méthode find(…). Il est possible de naviguer dans l'arborescence de projet, par exemple avec la méthode get_children() qui permet d'accéder aux objets enfants directs (comme les équipements de contrôleur). L'appel de la méthode get_children() à partir d'un objet enfant permet d'accéder aux objets enfants directs, et ainsi de suite.

NOTE : les méthodes disponibles varient suivant le type d'objet (POU, DUT, GVL, équipement). Il est recommandé d'utiliser inspectapi.dir(…) pour consulter la liste des méthodes d'API disponibles pour un objet donné.

Exemples

Ouvrir un projet avec la fonction d'API globale :

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)