JMRI: DecoderPro User Guide - Creating A Custom Decoder File

# JMRI: Guide Utilisateur DecoderPro

## Création d'un fichier décodeur personnalisé

Cette page fournit l'information sur la méthode de travail des fichiers de définitions pour le Programmateur Symbolique DecoderPro et comment en créer un nouveau.

Dans ce guide utilisateur, nous allons cheminer á travers le processus de création d'un fichier pour un nouveau décodeur. Vous pourrez tirer bénéfice de la lecture des autres sections de ce guide utilisateur DecoderPro pour obtenir des informations de fond, spécialement sur l'introduction XML et la section sur les Contenus des Fichiers de Configuration.

La meilleur méthode pour créer un fichier de configuration est de modifier un existant. Dans cette section nous allons utiliser cette méthode.

Faites une copie d'un fichier existant.

  Bien que vous puissiez appeler votre fichier comme bon vous semble, il travaillera mieux si vous utilisez les mêmes conventions que les fichiers fournis. C'est `"manufacturer name"_"decoder family".xml`, par exemple: `Digitrax_1x2.xml`et `Atlas_DualMode.xml`

  Pour les fichiers fournis, nous utilisons la même casse, etc, que celles que les fabricants de décodeurs utilisent dans leurs documentations.

  Ce nouveau fichier prendra place dans le sous-répertoire `decoders` dans le répertoire preferences `JMRI` ainsi le programme pourra le trouver. Le fichier`DecoderProConfig2.xml` se trouve dans le répertoire preferences, ainsi vous pouvez chercher ici pour localiser le fichier. (Voir la page de configuration des fichiers pour plus de détails sur ce répertoire et ce qu'il contient.

  Si vous modifiez une définition de décodeur, il vaut mieux commencer avec la version la plus récente, qui peut être trouvée ici sur le site web de JMRI à https://jmri.org/xml/decoders/. De cette façon il ne sera pas difficile de fusionner vos changements avec ceux qui pourrait avoir été fait entre temps. SVP Ne reformater pas plus que nécessaire. Si vous changez les données techniques dans les 5 ou 10 lignes du haut, ou reformater le contenu, il sera très difficile de savoir ce qui a été changé et ce qui ne l'a pas été .

Éditer le nouveau fichier

  Ouvrez le nouveau fichier avec votre éditeur de texte favori.

Contenu du fichier: En tête XML

  Vous verrez quelque chose comme ceci en haut du fichier ( les exemples viennent d'un fichier 0NMRA.xml )

  <?xml version="1.0" encoding="utf-8"?>
  <?xml-stylesheet type="text/xsl" href="../XSLT/decoder.xsl"?>
  <!-- Copyright (C) JMRI 2001, 2005, 2007, 2-009, 2010 All rights reserved -->
  ...
  <decoder-config xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://jmri.org/xml/schema/decoder.xsd">

  N'oubliez pas ces lignes; elles décrivent le format du fichier.

File contents: Author

  L'élément suivant décrit l'auteur et la version de ce fichier de décodeur:

  <version author="jake@physics.berkeley.edu"
  version="1" lastUpdated="20011201"/>

  Ces attributs ne sont lus que par les gens, pas par le programme, ainsi leur format exact n'est pas critique. Mais nous vous encourageons à insérer votre adresse courriel dans les fichiers que vous créez ou modifiez; ainsi celui qui a une question à poser sait où vous contacter. La version et les derniers attributs mis à jour fournissent un moyen de décrire les différentes versions d'une définition de décodeur à part,donc nous aimerions également que vous les mettiez à jour ceux. Pour un nouveau fichier, commencer à numéroter à "1" et si vous modifiez un fichier existant incrémenter l'attribut version au numéro suivant.

File contents: Decoder Family and Model
  Les lignes suivantes identifient la "famille" de décodeurs que ce fichier décrit:

  <decoder>
  <family name="Digitrax 1x2" mfg="Digitrax"
  lowVersionID="240" highVersionID="242"
  comment="Digitrax DH142, etc" >
  <model model="DH142" numOuts="4" numFns="2"/>
  <model model="DN142" numOuts="4" numFns="2"/>
  <model model="DH083" numOuts="5" numFns="2"/>
  </family>

  L'espacement n'est pas important, mais il est utilisé pour indenté le fichier et le rendre plus lisible. XML utilise "éléments" et "attributs" pour porter les informations. les choses <model> sont des éléments; les attributs comme numOuts sont fixés á des valeurs spécifiques á l'intérieur des éléments. Dans la 2ème á la 4ème lignes ci-dessus

  <family name="Digitrax 1x2" mfg="Digitrax"
  lowVersionID="240" highVersionID="242"
  comment="Digitrax DH142, etc" >

  L'élément est "family", avec les attributs "name", "mfg", "lowVersionID", "highVersionID", et "comment". Un attribut est une valeur donnée avec le signe égal et la valeur entre guillemets ( les guillemets sont obligatoires ). L'ordre des attributs n'est pas important, et vous pouvez cassez la lignes et la reprendre si cela rend le fichier plus facile á lire. Notez que tous les attributs doivent être entre crochets et après le nom de l'élément.

  Dans cet élément, changer les attributs pour correspondre au nouveau décodeur:

  - name - le nom de la famille de décodeur. C'est mieux si vous utilisez le même nom ici que celui que vous avez utilisé pour le nom de fichier.
  - mfg - le fabricant du décodeur. C'est mieux si vous utilisez le même nom de fabricant ici que celui que vous avez utilisé pour le nom de fichier.
  - lowVersionID, highVersionID - Le fabricant peut charger un numéro de version dans le CV 7 du décodeur.
  Tous les fabricants ne le font pas, mais si un est disponible, le programmateur peut vérifier si ce fichier est utilisé avec le type de décodeur attendu. Si une valeur est valide, définissez les attributs lowVersionID and highVersionID avec la même valeur, par exemple:

  lowVersionID="123" highVersionID="123"

  Si le type de décodeur peut avoir plus d'une rangée de numéro, par exemple parce que le fabricant a fait plusieurs mise á jour définissez les deux attributs pour couvrir la gamme:

  lowVersionID="21" highVersionID="42"

  Si vous ne connaissez pas le numéro de version, ne définissez pas un de ces attributs.Laissez les juste á off. lowVersionID par défauts á 0, highVersionID par défauts á 255 afin qu'ensemble, les valeurs par défaut signifie «toute valeur». comment - Ceci est optionnel. Vous pouvez inclure votre nom, ou autre info au sujet du changement dans le fichier.

  Les lignes suivantes:

  <model model="DH142" numOuts="4" numFns="2"/>
  <model model="DN142" numOuts="4" numFns="2"/>
  <model model="DH083" numOuts="5" numFns="2"/>

  vous permettent de lister un nombre de modèle de décodeurs différents qui peuvent utiliser ce fichier. Pour un simple décodeur, enlever tout sauf un et donnez lui le nom du "modèle" de décodeur. Le numOuts et numFns sont décrit plus tard, mais pour le moment vous pouvez les effacer laissant quelque chose comme:

  <model model="DH142" />

  L'élément modèle peut aussi contenir les attributs lowVersionID et/ou highVersionID , qui sont applicables á tout ce modèle. Si l'un n'apparait pas, la valeur ( ou sa valeur par défaut ) de l'élément famille sera utilisée .
File contents: Programming Modes

  L'élément suivant définit quel mode de programmation est comprit par le décodeur :

  <programming direct="byteOnly" paged= "yes"
  register= "yes" ops= "yes"></programming>

  Pagind, registerer et ops peuvent être régler soit á "yes" ou á "no". Direct peut être fixé á "no", "bitOnly", "byteOnly", ou "yes". Le programmateur utilise ces informations pour sélectionner le mode de programmation á utiliser pour travailler avec le décodeur.

File contents: Variable names

  La partie suivante du fichier consiste en un jeu d'éléments "variable" définissant des variables spécifiques, imbriquées dans un élément "variables"(notez le"s") Un exemple:

  <variables>
  <variable CV="1" item="Primary Address" default="03">
  <decVal min="1" max="127"/>
  <label>Short Address</label>
  <comment>NMRA standard form</comment>
  <tooltip>Digitrax systems only address 1-99</tooltip>
  </variable>
  (followed by more <variable> entries)
  (Insert new ones at the end)
  </variables>

  Chaque variable représente une chose á configurer. Elle peut représenter un CV simple, exemple une adresse, ou plusieurs bits qui doivent être configurer pour commanderr une fonction particulière. Si plusieurs de celles-ci ne sont pas appropriées pour votre décodeur, vous pouvez les supprimer. Soyez sûr d'enlever l'élément entier de la <variable> pour correspondre á la </variable>. Vous pouvez aussi les réarranger si vous préférez un ordre différent.

  Les attributs incluent:

  - item - Un nom alternatif "standard" pour cette variable. Voir la discussion sur la page des définitions des programmateurs pour plus de détails sur ceux-ci. Généralement, regarder le programmateur Complet pour trouver quelque chose de similaire, et utilisez le "nom" attribué.
  - CV - Quel CV contient l'information de configuration pour cette variable.
  - mask - Un modèle comme "XXXVVVXX" qui commande quels bits dans le CV mettent la variable up . Chaque "V" est un bit qui est inclut, et "X" sont des bits qui ne sont pas inclus. Il est mieux d'avoir huit caractères,comme cela nous savons où nous allons. Si la variable est un Octet complet, cette attribut peut être omit .
  - default - la valeur par défaut pour cette varable. C'est utilisé pour un nouveau décodeur, ou quand vous voulez remettre le décodeur á ses réglages d'usine

  (Il y en a un peu plus,que nous allons quitter pour la section avancée ci-dessous)

  L'élément "label" inclut fournit un nom de variable lisible. Ceci est généralement la façon dont les fabricants de décodeur appellent cet élément, même si le d'autres fabricants ou le NMRA utilisent un nom différent pour des choses similaires. C'est en option, auquel cas la valeur "élément" sera utilisé comme label quand il est présenté á l'utilisateur.

  L'élément "comment" vous permet d'ajouter des informations additionnelles pour les futures développeurs. cette information est visible quand la définition est éditée, mais n'est pas fournie aux simples utilisateurs de DecoderPro

  L'élément "tooltip" lvous permet de fournir des informations supplémentaires á l'utilisateur quand celui-ci survole avec le curseur la variable á l'écran. /dd>

File contents: Creating new Variable definitions

  Vous pouvez aussi définir de nouvelles variables. Un bon point de départ est de copier une définition similaire, changer son nom d'élément par une nouvelle valeur et éditer son contenu.

  Pour définir comment la nouvelle variable est affichée et éditée, vous ajoutez l'élément au sein de l'élément "variable". Il y a plusieurs formes possibles:

  - Pour une valeur décimale, vous incluez un élément decVal comme l'exemple ci-dessus. Les deux attributs possibles sont min et max, qui définissent la fourchette de valeurs acceptables. Si vous les omettez les valeurs entre 0 et 255 seront permises.
  - Si vous préférez entrer et afficher des valeurs en hexadécimal, utilisez l'élément "hexVal".c'est le même que l'élément "decVal" dont nous avons déjá discuté mais en hexa.
  - Si votre décodeur supporte les adresses longues, vous pouvez ajouter un élément 'longAddress'. C'est peut être plus simple de copier ceci depuis un autre fichier, ou depuis cet exemple:

  <variable name="Long Address" CV="17">
  <longAddressVal/>
  </variable>

  Si votre décodeur le supporte, vous pouvez entrer un élément "speedTableVal" pour la table de vitesse. Les attributs optionnels sont "entries","min", "max" et "mfx" (quand vrai active le style Märklin mfx® de la table de vitesse. Exemple:

  <variable name="Speed Table" CV="67">
  <speedTableVal/>
  </variable>

  Quelques options de décodeur sont mieux représenter par "choisir un choix".Elles sont représentées par un élément enumVariable. Exemple:

  <variable name="F6 during DC operation" CV="13" mask="XXVXXXXX">
  <enumVal>
  <enumChoice choice="Off"/>
  <enumChoice choice="On"/>
  </enumVal>
  </variable>

  Chaque élément enumChoice décrit une possibilité. Il peut y en avoir autant que désiré. pour le choix d'un bit, vous utilisez deux éléments enumChoice comme dans l'exemple. Pour un choix de 4 bits, comme les codes FX dans les décodeurs Digitrax, vous pouvez utiliser jusqu'á 16 choix. Ils sont affichés dans l'ordre où ils ont été entrés dans le fichier, et sont aussi numérotés dans cet ordre. Si le premier est choisi, un 0 est entré dans les bits CV; choisir le second stocke 1; etc.

  Si vous avez besoin de spécifier un nombre spécifique pour une option enum, ajoutez un attribut "value":

  <enumChoice choice="Blue" value="32"/>

Vérification des erreurs de syntaxe

  A ce point, vous avez créé un nouveau fichier de configuration!

  Vous pouvez vérifier la syntaxe en sélectionnant l'élément"Validate XML file" dans le menu "Débogage". Il ouvre un dialogue de sélection de fichier; sélectionnez votre fichier et cliquez "open". Si tout est bon, vous obtenez une boite de dialogue qui dit "OK". Si non , vous obtiendrez un message d'erreur complètement incompréhensible. La seule partie utilisable de ce message est le numéro de la ligne; ouvrez un éditeur á cette ligne et essayer de trouver le problème de syntaxe.

Ajouter le fichier á l'index

  Tout ce qui reste est d'entrer votre nouveau fichier dans l'index. Cet index est utilisé pour accélérer le démarrage, quand la liste des décodeurs disponibles est construite .

  Sélectionner l'élément "Créer Index Décodeur" depuis le menu "Débogage"

Félicitations! Vous avez fini. Ensuite, ouvrez l'application programmateur et essayez le

Pour des informations plus avancées sur le contenu des fichiers, svp voir la page Advanced Decoder Definitions.