Comment programmer Pepper avec Chorégraphe et python ?

[Mise à jour le 10/1/19]

Cette page est une traduction du document Boîtes de script Python.

Par défaut, lorsque vous créez une boîte Python, son script se présente comme ci-dessous:

class MyClass(GeneratedClass):
    def __init__(self):
        GeneratedClass.__init__(self)
 
    def onLoad(self):
        #~ puts code for box initialization here
        pass
 
    def onUnload(self):
        #~ puts code for box cleanup here
        pass
 
    def onInput_onStart(self):
        #~ self.onStopped() #~ activate output of the box
        pass
 
    def onInput_onStop(self):
        self.onUnload() #~ it is recommended to call onUnload of this box in a onStop method, as the code written in onUnload is used to stop the box as well
        pass

Vous pouvez voir ci-dessus que le script contenu dans une boîte définit une classe nommée MyClass. Cette classe hérite de GeneratedClass. MyClass a déjà quelques méthodes définies par défaut.

En fait, MyClass est la classe représentant la boîte.

GeneratedClass est une classe qui est automatiquement générée. Elle comprend toutes les informations concernant la boîte ( entrées, sorties, paramètres, etc.). Elle contient également des fonctions qui pourraient vous être utiles dans l'écriture du script (built-in functions of the box script).

Le fait que MyClass hérite de GeneratedClass vous permet d'utiliser ces fonctions (built-in) dans le script.

De plus, comme vous pouvez éditer MyClass, vous pouvez ajouter vos propres fonctions.

Dans le script d'une boîte, il existe de nombreuses méthodes disponibles, vous permettant de gérer:

• Les entrées (Inputs),
• Les sorties (Outputs),
• Les paramètres (Parameters),
• Timeline,
• Les évènements (Load and unload events),
• Les ressources (Resources),
• Proxies,
• Le système de fichiers (File system),
• Les journaux (Logs).
• Les exceptions (Exception handling).

Les méthodes correspondant aux entrées de la boîte doivent être définies dans le script avec la syntaxe suivante: onInput_ <nom-entrée>.

Cette méthode est appelée chaque fois qu'une entrée est activée.

Par exemple, si une entrée s'appelle myInput et est un Bang, les lignes suivantes doivent définir sa méthode correspondante:

def onInput_myInput(self):
    # The code of my method
    pass

Si myInput est un nombre (Number), les lignes suivantes doivent définir sa méthode :

def onInput_myInput(self, number):
    # The code of my method
    pass

L'argument number est la valeur du signal présenté à l'entrée de la boîte.

Si myInput est un Dynamic et qu'elle peut être stimulée par un nombre ou un Bang, vous pouvez utiliser les lignes suivantes:

def onInput_myInput(self, number = None):
    # The code of my method
    pass

L'argument number est:

• la valeur du signal envoyé sur l'entrée ou
• est égal à None s'il est stimulé par un Bang.

Les méthodes correspondant aux sorties de la boîte ne sont pas présentes dans le script mais sont déjà définies avec la syntaxe suivante: <nom-sortie>.

La sortie est stimulée chaque fois qu'une méthode correspondant à une sortie est appelée.

Par exemple, si une sortie s'appelle myOutput et est un Bang, la ligne suivante vous permet de stimuler la sortie:

self.myOutput()

Si myOutput est un nombre, les lignes suivantes vous permettent de stimuler la sortie avec la valeur de myNumber:

myNumber = 3
self.myOutput(myNumber)

Si votre sortie s'appelle onError, elle sera automatiquement déclenchée et fournira chaîne représentative de l'erreur si une exception est levée . Voir “La Gestion des exceptions”.

La fonction Get Parameter vous permet d’obtenir la valeur de tout paramètre de la boîte.

Par exemple, si la boîte a un paramètre nommé My parameter, la commande pour obtenir la valeur de ce paramètre sera:

value = self.getParameter("My parameter")

Cette fonction lancera une exception si aucun paramètre de ce type n'existe.

La fonction de rappel setParameter peut être surchargé. Elle sera appelé lorsque le paramètre change.

Par exemple, si la boîte contient un paramètre nommé My parameter, ce script sera appelé lors du changement de ce paramètre:

def setParameter(self, parameterName, newValue):
    if(parameterName == "My parameter"):
      self.logger.info("My parameter has been changed to  " + str(newValue))

Ces méthodes vous permettent de modifier le scénario de la boîte à partir de son script ou du script d'une boîte interne.

Pour accéder à un objet Timeline en python, utilisez:

self.getTimeline() pour gérer le scénario de la boîte en cours ou self.getParentTimeline() pour gérer le scénario de la boîte parent. pour en savoir plus

Méthodes automatiquement appelées lorsque la boîte est chargée ou déchargée.

onLoad est appelé lorsque la boîte est chargée. Elle est défini comme suit:

def onLoad(self):
    # The code of my method
    pass

onUnload est appelé lorsqu'il est déchargé. Il est défini comme suit:

def onUnload(self):
    # The code of my method
    pass

Il est conseillé d'appeler onUnload dans le code des méthodes correspondant aux entrées onStop pour que la boîte soit réinitialisée à l'arrêt.

ALProxy vous permet de créer un proxy sur un module NAOqi, puis d'utiliser facilement n'importe quelle méthode de ce module.

Par exemple, si vous souhaitez créer un proxy sur ALLeds et utiliser la méthode rasta, vous pouvez utiliser les lignes suivantes dans votre fonction:

leds = ALProxy("ALLeds")
leds.rasta()

Vous devrez peut-être connaître l'emplacement de votre comportement (behavior) dans le système de fichiers.

Par exemple, si vous souhaitez exécuter le comportement do_something de votre application, vous devez connaître l'UID du package représentant votre application:

alBehaviorManager = ALProxy("ALBehaviorManager")
alBehaviorManager.runBehavior(self.packageUid() + '/do_something')

Par exemple, pour accéder à un fichier hello.wav, situé dans le dossier behavior, utilisez:

path = os.path.join(self.behaviorAbsolutePath(), 'hello.wav')

Pour accéder à une ressource de votre application, procurez-vous le chemin permettant d'y accéder. Vous pouvez le faire en remplaçant le chemin absolu précédent par un chemin relatif.

application_path = self.behaviorAbsolutePath().replace(self.behaviorRelativePath(), "")

Ces méthodes vous permettent d'imprimer des messages dans la fenêtre de Logs (Log viewer).

En effet, vous avez peut-être remarqué que vous ne pouvez rien écrire dans la fenêtre de débogage en utilisant dans un script l'instruction d'impression. Vous devez utiliser des commandes spécifiques détaillées ci-dessous:

Par exemple, quelque chose comme:

def onInput_onStart(self):
   self.log("This is an info message")
 
   self.logger.fatal("This is a fatal message")
   self.logger.error("This is an error message")
   self.logger.warning("This is a warning message")
   self.logger.info("This is an other info message")
   self.logger.debug("This is a debug message")

s'affiche dans la fenêtre de débogage:

Des exceptions peuvent être émises par différents scripts, par exemple lors de la création de proxy vers des modules absents.

Si une exception n'est pas interceptée par votre code Python, l'erreur se propagera et arrêtera le comportement.

Pour empêcher l'arrêt d'un comportement, vous devez soit intercepter les exceptions directement dans votre code Python, soit ajouter une sortie onError.

Pour ce faire, créez une sortie nommée onError, avec la nature onStopped et le type String. Chaque fois qu'une exception est déclenchée et non capturée, la sortie onError est déclenchée et renvoie le message de l'exception.

Si vous souhaitez effectuer des traitements spéciaux sur les données, vous devrez importer des modules python tels que math ou string.

Ceci est fait par l'instruction d'importation en haut du code du script.

Voici un exemple de code qui montre comment importer un module math:

class MyClass(GeneratedClass):
   def __init__(self):
      GeneratedClass.__init__(self)
 
   def onLoad(self):
      #~ puts code for box initialization here
      pass
 
   def onUnload(self):
      #~ puts code for box cleanup here
      pass
 
   def onInput_onStart(self):
      import math #Import the math module
      self.tan = math.tan(p)
      self.onStopped(self.tan)
      pass
 
   def onInput_onStop(self):
      self.onUnload() #~ it is recommended to call onUnload of this box in a onStop method, as the code written in onUnload is used to stop the box as well
      pass