JMRI: Getting Started with Scripting

## JMRI: Mise en Route avec des Scripts

### Exécuter "Bonjour le monde"

Il y a plusieurs façons d'utiliser des scripts Python avec JMRI. Le plus simple est d'utiliser le support intégré dans les applications standards de JMRI : PanelPro, DecoderPro, etc. Pour ce faire:

- Dans le menu "Panneaux" , sélectionnez "entrée de script". Cela vous donnera une fenêtre où vous pourrez taper une ou plusieurs commandes à exécuter. (Notez que cela pourrait prendre un peu de temps la première fois que vous faites cela tandis que le programme trouve ses bibliothèques, il sera plus rapide la prochaine fois) Les commandes restent dans la fenêtre, donc vous pouvez les éditer et les relancer jusqu'à ce qu'elles vous conviennent.
- Dans le menu "Panneaux" , sélectionnez "sortie du script". Cela crée une fenêtre qui montre la sortie de la commandes de script que vous émettez.
- Pour le voir en fonctionnement, tapez

      print "Bonjour le monde"

  dans la fenêtre de saisie et cliquez sur "Exécuter". Vous devriez voir immédiatement la fenêtre sortie du script :

      print "Bonjour le monde"
      Bonjour le monde

- Python évalue également les expressions, etc. Retirez le contenu de la fenêtre d'entrée (le sélectionner et appuyez sur supprimer), et entre

      print 1+2

  puis cliquez sur exécuter. La fenêtre de sortie doit alors montrer quelque chose comme

      print 1+2
      3

### Commandes Simples réseau

    >>> lt1 = turnouts.provideTurnout("1")

    >>> lt1.setCommandedState CLOSED #(DROIT)

    >>> print lt1.commandedState
    2

    >>> lt1.commandedState = THROWN  #(DÉVIÉ)

    >>> print lt1.commandedState
    4

    >>> turnouts.provideTurnout("1").getCommandedState()
    1

Notez que ce n'est qu'en exécutant une version complète de l'application JMRI; toutes les fenêtres et les menus sont présentés de la même façon, la configuration est faite par le panneau des préférences, etc. que la connexion Jython ajoute une ligne de commande à partir de laquelle vous pouvez manipuler directement les choses.
Cela montre aussi certaines des simplifications que Jython et le langage Python apporte à l'usage du code JMRI. La fonction membre de Java:

    turnout.SetCommandedState (jmri.Turnout.CLOSED);

peut aussi être exprimée en Jython:

    turnout.commandedState = CLOSED  # DROIT

Il en résulte un code beaucoup plus facile à lire.

Il ya beaucoup de livres utiles et de didacticiels Python en ligne. Pour plus d'informations sur le langage Jython et en relations avec Java, la meilleure référence est le Jython Essentials livre publié par O'Reilly. Le site web jython.org est également très utile.

### Accès à JMRI

JMRI utilise longuement le modèle-type pour obtenir l'accès aux objets. En Java il en résulte un code verbeux comme a

        L'aiguillage t2 = InstanceManager.turnoutManagerInstance () newTurnout ("LT2", "turnout 2.");
        t2.SetCommandedState (Turnout.THROWN)

Jython simplifie ceci, en nous permettant de fournir des variables utiles, et par le raccourcissement de certaines méthodes d'appels

Pour avoir accès à des gestionnaires Cible Signal, capteur et aiguillage et de l'objet CommandStation, plusieurs variables raccourcies sont définies:

- capteurs
- aiguillages
- lumières
- Signaux (Cibles Signal)
- mâts (Mâts Signal)
- itinéraires
- Cantons
- Rapports
- mémoires
- gestionnaire d'alimentation
- programmateurs
- DCC (centrale digitale)
- arrêt (gestionnaire d'arrêt en cours)
- audio/

Ceux-ci peuvent ensuite être référencées directement dans Jython comme a

        t2 = turnouts.provideTurnout ("12");

        dcc.sendPacket (new byte [] {0x12, 0x32, 0x4E}, 5)

Notez que la variable T2 n'a pas besoin d'être déclarée.

Jython fournit un raccourci pour les paramètres qui ont été définis avec les méthodes obtenir et définir comme Java-Bean:

        t2.SetCommandedState (Turnout.THROWN)

peut être écrite comme

        t2.commandedState = THROWN #(DEVIE)

Où l'attribution invoque en réalité la méthode d'ensemble. Notez également que THROWN a été défini lors de l'exécution du script Python au démarrage, CLOSED, ACTIVE, INACTIVE, RED, YELLOW et GREEN sont également définis. (Les raccourcis sont tous définis dans un fichier appelé "jmri_defaults.py" que vous pouvez trouver dans le répertoire "jython" de la distribution)

Un mécanisme similaire peut être utilisé pour vérifier l'état de chose:

    >> Sensors.provideSensor> print ("3"). KnownState == ACTIVE
    1
    > Sensors.provideSensor>> print ("3"). KnownState == INACTIVE
    0

Notez que Jython utilise des "1" pour indiquer vrai, et "0" pour indiquer faux, de sorte que capteur 3 est actuellement actif dans cet exemple. Vous pouvez également utiliser les symboles "true" et "false", respectivement.

Vous pouvez appeler directement des méthodes plus compliquées, par exemple envoyer un paquet DCC sur les rails, vous tapez:

        dcc.sendPacket ([0x01, 0x03, 0xbb], 4)

Cela envoie ce paquet de trois octets quatre fois, puis retourne à la ligne de commande.

### Les fichiers de script, les auditeurs et les classes

Scripting ne serait pas très intéressant si vous aviez à taper les commandes à chaque fois. Ainsi, vous pouvez mettre des scripts dans un fichier texte et les exécuter en sélectionnant l'élément de menu "Exécuter le script ..." , ou en utilisant les "Préférences avancées" pour exécuter le fichier script et le programme commence.

Bien que les énoncées ci-dessus que nous avons montrées étaient si rapides que vous ne pouviez pas les voir, le reste du programme a été en attente pendant que vous exécutez ces échantillons. Ce n'est pas un problème pour un couple de déclarations, ou pour un fichier de script qui n'a tout simplement que peu de choses (peut-être fixer un couple d'aiguillage, etc) et quitter. Mais vous voudrez peut-être que les choses se passent sur une plus longue période, ou peut-être même attendre que quelque chose se passe sur le réseau avant que certaines partie de votre script ne s'exécutent. Par exemple, vous voudrez peut-être inverser une locomotive lorsque certains capteurs indiquent qu'il a atteint la fin de la voie.

Il y a deux façons de faire cela. D'abord, votre script peut définir un "auditeur", et l'attacher à un capteur particulier, l'aiguillage , etc Un auditeur est une petite sous-routine qui est appelée quand tout ce qui lui est attaché a un changement d'état. Par exemple, un sous-programme auditeur attaché à un aiguillage particulier est appelé lorsque l'aiguillage va de dévié à droit, ou de droit à dévié. La sous-routine peut alors regarder autour, et décider que faire, et exécuter les commandes nécessaires. Lorsque les sous-routines retournent, le reste du programme se poursuit ensuite jusqu'à ce que l'auditeur a un nouveau le changement d'état de l'objet , alors le processus se répète.

Pour les choses plus compliquées, où vous voulez vraiment que votre code de script soit autonome dans le programme, vous définissez une "classe" qui fait ce que vous voulez. Dans la forme courte, cela vous donne un moyen d'avoir une exécution de code indépendante à l'intérieur du programme. Mais ne vous souciez pas de cela jusqu'à ce que vous ayez eu plus d'expérience avec les scripts.