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.
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.xmlet 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
fichierDecoderProConfig2.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é .
Ouvrez le nouveau fichier avec votre éditeur de texte favori.
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.
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.
<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:
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 .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.
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:
(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>
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:
<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>
<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"/>
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.
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.
Faites un don à JMRI.org