help/en/html/hardware/loconet/Addressing.shtml

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">

<html lang="en">
<head>
  <meta name="generator" content=
  "HTML Tidy for Mac OS X (vers 31 October 2006 - Apple Inc. build 15.17), see www.w3.org">

  <title>JMRI Hardware Support - LocoNet&reg; Addressing</title>
  <meta content="Bob Jacobsen" name="Author">
  <meta name="keywords" content=
  "JMRI LocoNet Address Addressing Sensors Turnout">
  <!-- The combination of "Define" and {Header,Style, Logo and Footer} comments -->
  <!-- are an arbitrary design pattern used by the update.pl script to -->
  <!-- easily replace the common header/footer code for all the web pages -->
  <!-- Style -->
  <meta http-equiv="Content-Type" content=
  "text/html; charset=us-ascii">
  <link rel="stylesheet" type="text/css" href="/css/default.css"
  media="screen">
  <link rel="stylesheet" type="text/css" href="/css/print.css"
  media="print">
  <link rel="icon" href="/images/jmri.ico" type="image/png">
  <link rel="home" title="Home" href="/"><!-- /Style -->
</head>

<body>
  <!--#include virtual="/Header" -->

  <div class="nomenu" id="mBody">
    <div id="mainContent">
      <h1>Support: LocoNet&reg; addressing</h1>

      <ul class="snav">
        <!-- h2 TOC -->
        <li><a href="#turnouts">Turnouts</a></li>

        <li><a href="#sensor">Sensors</a></li>

        <li><a href="#transponding">Transponding</a></li>

        <li><a href="#SVs">SVs</a></li>
      </ul>

      LocoNet&reg; systems address input Sensors and output
      Turnouts using numbers. This page describes how those numbers
      are defined in JMRI, and how they relate to the numbers in
      other (hardware) systems.

      <h2>Adding an item to the table</h2>
      <p>When you add an item to one of the tables, you only
            have to enter the numbers to have JMRI construct
            the complete system name.<br>
            Here's a summary, split up for
            outputs (eg. Turnouts) and inputs (eg. Sensors):</p>

      <table>
        <tbody><tr>
            <th>In/Out</th>
            <th>Entry</th>
            <th>Meaning</th>
            <th>makes System Name</th>
            <th>Mask</th>
            <th>Equivalent</th>
            <th>Minimum</th>
            <th>Maximum</th>
        </tr>
        <tr>
            <td>i</td>
            <td>34</td>
            <td>Sensor 34</td>
            <td>LS34</td>
            <td>integer</td>
            <td>N/A</td>
            <td>1</td>
            <td>4096</td>
        </tr>
        <tr>
            <td>o</td>
            <td>34</td>
            <td>Turnout 34</td>
            <td>LT34</td>
            <td>integer</td>
            <td>N/A</td>
            <td>1</td>
            <td>4096</td>
        </tr>
        </tbody></table>
      <!-- this table is an exceprt from the table in the help/en/html/doc/Technical/Names.shtml
      based on information from the Hardware help pages
      by Egbert Broerse @silverailscolo July 2017 -->

      <a name="turnout" id="turnout"></a>
      <h2>Addressing LocoNet Turnouts</h2>

      <p>Inside packets on the LocoNet, output Turnouts are
      addressed with numbers from 0 to 4095. Throttles, however,
      address these with numbers from 1 to 4096. To avoid user
      confusion, JMRI uses the same numbering as the Throttles for
      Turnout System Names: LT1 to LT4096.</p>

      <p>Note that when the LocoNet Monitor panel shows the
      contents of the LocoNet packets in text, it uses the same
      addressing, hence 1 to 4096. This is then different from the
      raw bytes that are displayed, but at least it's consistent
      with what users expect to see. We agree that's confusing, but
      there has to be some confusion somewhere, given the way this
      was set up.</p>

      <h3>The Turnout Table</h3>

      <p>The JMRI Turnout Table shows a list of all Turnouts JMRI
      is aware of. Every time JMRI sees a LocoNet message which
      specifies a Turnout, JMRI updates an existing entry in the
      Turnout Table or creates a new entry if one does not already
      exist. Each Turnout in the table can also be assigned a "User
      Name".</p>

      <p>The Turnout Table provides a useful snapshot of the
      current state of all known Turnouts, and allows the user to
      change the state of those Turnouts.</p>

      <p>Additional information on Turnouts and the Turnout Table
      may be found at the <a href="../../tools/Turnouts.shtml">main
      Turnouts page</a>.</p><a name="sensor" id="sensor"></a>

      <h2>Addressing LocoNet Sensors</h2>
      Inside packets on the
      LocoNet, Sensors are addressed with numbers from 0 to 4095.
      Digitrax documentation refers to these as 1 to 4096, however.
      Just like Turnouts, we use the documentation numbering to
      define the Sensor System Names: LS1 to LS4096.

      <p>The simplest way to find the right number for a given
      Block is to open a "LocoNet monitor" window, and drop a
      locomotive onto the Block you're interested in. You'll see
      the LocoNet message, complete with number, in the window that
      looks something like this:</p>
      <pre>
   General sensor input report: contact 161 (DS54 switch 81 Aux input) (BDL16 11,1) is Hi 
</pre>
      The contact number, 161 in this case, is the address of the
      Sensor. Prefix that with LS to get the Sensor System Name, e.g.
      LS161 in this case.

      <p>If you wish to manually enter in the hardware address to
      the system you can do it by enter in the board number,
      followed by the channel number separated by a ":"<br>
      So for a Sensor on board 11, channel 1 you would enter into
      the Hardware Address field : <b>11:1</b></p>

      <p>If you want to calculate the address of a BDL168 input,
      you can use: <code>    number = 16 * (board number) +
      (channel number) - 16</code> where "channel number" runs from
      1 to 16. For example, the first circuit (number 1) on board
      11 has number: <code>    number = 16 * (11) + (1) - 16 =
      161</code> as we saw in the example above.</p>

      <p>If you want to calculate the address of a DS64 or DS54 aux input,
      use: <code>    number = 2 * (turnout number - 1) + 1</code>
      For example, the aux input associated with turnout 81 has
      number: <code>    number = 2 * (81 - 1) + 1 = 161</code> If
      it's the switch input, you add one more to that: <code>   
      number = 2 * (turnout number - 1) + 2</code></p>

      <p>For example, the switch input associated with turnout 12
      has number:</p><code>    number = 2 * ( 12 - 1 ) + 2 =
      24</code>

      <h3>The Sensor Table</h3>

      <p>The JMRI Sensor Table shows a list of all Sensors JMRI is
      aware of. Every time JMRI sees a LocoNet message which
      specifies a Sensor, JMRI updates an existing entry in the
      table or creates a new entry if one does not already exist.
      Each Sensor in the table can be assigned a "User Name".</p>

      <p>The Sensor Table provides a useful snapshot of the current
      state of all known Sensors.</p>

      <p>Additional information on Sensors and the Sensor Table may
      be found at the <a href="../../tools/Sensors.shtml">main
      Sensors page</a>.</p><a name="transponding" id=
      "transponding"></a>

      <h2>Addressing Transponding</h2>

      <p>Digitrax Transponding is handled via the Reporter
      mechanism in JMRI. Reporters gather information from the
      layout and make it available when it changes. JMRI refers to
      Reporters using the System Name <i>LRx</i> where <i>x</i> is
      a number which corresponds to a detection zone.</p>

      <p>The Transponding zones are numbered sequentially from 1 to
      4096. Current BDL16x hardware implements only odd-numbered
      Transponding zones. The first Transponding zone of a BDL16x
      board is reported as Reporter number <span style=
      "font-family: monospace">(1 +(board address -1) * 16)</span>.
      The second Transponding zone of a BDL16x board is reported as
      Reporter number <span style="font-family: monospace">(1
      +(board address -1) * 16) + 2</span>.</p>

      <p>Reporter numbering is summarized in the table below:</p>

      <table border="2">
        <tr align="center">
          <td>Board Address</td>

          <td>Zone</td>

          <td>Reporter Number</td>
        </tr>

        <tr align="center">
          <td rowspan="8">1</td>

          <td>A</td>

          <td>LR1</td>
        </tr>

        <tr align="center">
          <td>B</td>

          <td>LR3</td>
        </tr>

        <tr align="center">
          <td>C</td>

          <td>LR5</td>
        </tr>

        <tr align="center">
          <td>D</td>

          <td>LR7</td>
        </tr>

        <tr align="center">
          <td>E</td>

          <td>LR9</td>
        </tr>

        <tr align="center">
          <td>F</td>

          <td>LR11</td>
        </tr>

        <tr align="center">
          <td>G</td>

          <td>LR13</td>
        </tr>

        <tr align="center">
          <td>H</td>

          <td>LR15</td>
        </tr>

        <tr align="center">
          <td rowspan="8">2</td>

          <td>A</td>

          <td>LR17</td>
        </tr>

        <tr align="center">
          <td>B</td>

          <td>LR19</td>
        </tr>

        <tr align="center">
          <td>C</td>

          <td>LR21</td>
        </tr>

        <tr align="center">
          <td>D</td>

          <td>LR23</td>
        </tr>

        <tr align="center">
          <td>E</td>

          <td>LR25</td>
        </tr>

        <tr align="center">
          <td>F</td>

          <td>LR27</td>
        </tr>

        <tr align="center">
          <td>G</td>

          <td>LR29</td>
        </tr>

        <tr align="center">
          <td>H</td>

          <td>LR31</td>
        </tr>

        <tr align="center">
          <td rowspan="8">3</td>

          <td>A</td>

          <td>LR33</td>
        </tr>

        <tr align="center">
          <td>B</td>

          <td>LR35</td>
        </tr>

        <tr align="center">
          <td>C</td>

          <td>LR37</td>
        </tr>

        <tr align="center">
          <td>D</td>

          <td>LR39</td>
        </tr>

        <tr align="center">
          <td>E</td>

          <td>LR41</td>
        </tr>

        <tr align="center">
          <td>F</td>

          <td>LR43</td>
        </tr>

        <tr align="center">
          <td>G</td>

          <td>LR45</td>
        </tr>

        <tr align="center">
          <td>H</td>

          <td>LR47</td>
        </tr>

        <tr align="center">
          <td colspan="3">...</td>
        </tr>

        <tr align="center">
          <td rowspan="4">256</td>

          <td>A</td>

          <td>LR4081</td>
        </tr>

        <tr align="center">
          <td>B</td>

          <td>LR4083</td>
        </tr>

        <tr align="center">
          <td colspan="2">...</td>
        </tr>

        <tr align="center">
          <td>H</td>

          <td>LR4095</td>
        </tr>
      </table><a name="reporter" id="reporter"></a>

      <h3>The Reporter Table</h3>

      <p>The JMRI Reporter Table shows a list of all Reporters JMRI
      is aware of. JMRI creates an entry in this table for each new
      Transponding zone for which it sees a Transponding message.
      Each Reporter in the table can be assigned a "User Name".</p>

      <p>Once you have the Transponding hardware installed and at
      least one Locomotive transponding properly, it is simple to
      fill in the Reporter Table for each Transponding zone by
      running the transponding Locomotive through all
      transponding-capable zones. It may be convenient to fill in a
      "User Name" in the JMRI Reporter Table at the same time when
      the Locomotive first enters each Transponding zone.</p>

      <p>Additional information on Reporters and the Reporter Table
      may be found at the <a href=
      "../../tools/Reporters.shtml">main Reporter
      page</a>.</p>

      <a name="SVs" id="SVs"></a>
      <h2>Addressing LocoNet device System Variables (SVs)</h2>
      <p>(The following was first fully available in <a href=
      "http://jmri.org/releasenotes/jmri4.1.2.shtml">JMRI
      4.1.2</a>. Versions before that may not be complete).</p>

      <p>Like decoders store Configuration Variables (CVs) to hold
      their settings, some LocoNet-compatible devices have System
      Variables (SVs).</p>

      <p>There are (at least) two variations of the protocol for
      accessing these. JMRI can use version 1 or version 2 to
      access compatible SVs by selecting "System Variable Type 1"
      or "System Variable Type 2" as the programming mode,
      respectively. This option is presented when you're using a
      LocoNet System Connection that actually connects to a
      LocoNet, such as a LocoBuffer-USB or PR3 in MS100 mode.</p>

      <p>SVs are numbered from 1 to 127 for version 1 hardware and
      from 1 to 2^16-1 = 65,535 for version 2 hardware. Their names
      can be written in several formats:</p>

      <ul>
        <li>nnnn, e.g. 12345 - Like regular CVs, this is the format
        to read and write an entire byte.</li>

        <li>nnnnL, e.g. 123L - (version 2 only) This means read or
        write four bytes at a time. This is more efficient for
        large variables, but note that you should be careful not to
        define overlapping CVs that point to the same memory:
        having CV10L and CV12L present will cause confusion, as
        will having both CV12L and CV13 present.</li>

        <li>nnnn^HH, e.g. 123^80 - (version 2 only) This means a
        masked write. Only the bits marked with a 1 in the two hex
        digits after the "^" character will be written to the
        device. In the example case, that means just the
        most-significant bit will be written. The values of the
        other bits currently in the device are not changed. This is
        a bit subtle, so we provide some examples.

          <table border="2">
            <tr>
              <th>CV<br>
              Number</th>

              <th>Prior<br>
              Content</th>

              <th>Value<br>
              Written</th>

              <th>Masked<br>
              Value</th>

              <th>New<br>
              Content</th>
            </tr>

            <tr>
              <td></td>
            </tr>

            <tr>
              <td>CV1^01</td>

              <td>0x55</td>

              <td>0x22</td>

              <td>0x01</td>

              <td>0x23</td>
            </tr>

            <tr>
              <td>CV1^01</td>

              <td>0x54</td>

              <td>0x22</td>

              <td>0x01</td>

              <td>0x22</td>
            </tr>

            <tr>
              <td>CV1^0F</td>

              <td>0x55</td>

              <td>0x33</td>

              <td>0x03</td>

              <td>0x53</td>
            </tr>

            <tr>
              <td>CV1^F0</td>

              <td>0x55</td>

              <td>0x33</td>

              <td>0x03</td>

              <td>0x53</td>
            </tr>

            <tr>
              <td>CV1^33</td>

              <td>0xF0</td>

              <td>0x77</td>

              <td>0x30</td>

              <td>0x37</td>
            </tr>
          </table>Note that, unlike the JMRI "mask" attribute, the
          value is not shifted over to match the mask bits. This is
          perhaps best used for single bit values via enum
          variables, where the specified choices can have the right
          bit coding. Or don't use it at all, and rely on
          DecoderPro to write the combined values of full words
          properly.
        </li>
      </ul>

      <h3>SV version 1 board addressing</h3>In some documentation,
      the SV version 1 protocol uses a two part address: 83/1, for
      example. (SV version 2 uses a single number with up to 14
      bits; 0 is not used) There doesn't seem to be a standard way
      to map that to a single number. JMRI maps A/B to (B-1)*256+A.
      Most boards seem to use N/1 addresses, so this makes that
      correspond to just N in JMRI. To summarize:

      <table border="2">
        <tr>
          <th width="80px">Old<br>
          Style</th>

          <th width="80px">JMRI<br>
          Number</th>
        </tr>

        <tr>
          <td>10/1</td>

          <td>10</td>
        </tr>

        <tr>
          <td>83/1</td>

          <td>83</td>
        </tr>

        <tr>
          <td>83/2</td>

          <td>339</td>
        </tr>

        <tr>
          <td>83/0</td>

          <td>-173</td>
        </tr>
      </table>Note that N/0 addresses do special operations, and
      aren't really addresses: They turn the programming messages
      into commands. They're available using negative numbers as
      above, but they're really not recommended!

      <h3>Using this in a DecoderPro "board" definition</h3>You can
      use all of the DecoderPro tools to manage a board using the
      LocoNet SV protocol if you provide an appropriate definition
      file. These are in the same format as a decoder definition
      file, except that to specify the LocoNet SV Version 2
      protocol you modify the "programming" element to looks like:
      <pre style="font-family: monospace;">
    &lt;programming direct="no" paged="no" register="no" ops="no"&gt;
        &lt;mode&gt;LOCONETSV2MODE&lt;/mode&gt;
    &lt;/programming&gt;
</pre>

      <p>LocoNet SV Version 1 protocol is the same exception you
      specify LOCONETSV1MODE. For more information, see the
      <a href="">schema definition file</a>.</p>

      <p>Note that the version 1 protocol is no longer recommended.
      If you're writing a decoder definition for a board that can
      use both, you should skip version 1 by providing just the
      LOCONETSV2MODE option.</p>

      <a name="boards" id="boards"></a>
      <h2>Addressing Op Switches in Digitrax boards</h2>
      <p>(The following was first fully available in <a href=
      "http://jmri.org/releasenotes/jmri4.9.7.shtml">JMRI
      4.9.7</a>. Versions before that may not be complete).</p>

        <p>Digitrax boards like the PM4, BDL168, SE8c and 
        DS64 use a special protocol to program their Op Switches.
        If you specify a programming mode of LOCONETBDOPSWMODE,
        DecoderPro will use that protocol.</p>
        
        <p>CVs are specified with the format "113.3", 
        where the part after the period is the specific
        Op Switch number, and the part before is 
        board-specific:<p>
        <UL>
            <LI>0x70 - 112 - PM4
            <LI>0x71 - 113 - BDL16
            <LI>0x72 - 114 - SE8
            <LI>0x73 - 115 - DS64
        </UL>
        

    <hr>

      <p>LocoNet&reg; is a registered trademark of <a href=
      "http://www.digitrax.com">Digitrax, Inc.</a></p>
    </div><!--#include virtual="/Footer" -->
  </div><!-- closes #mainContent-->
  <!-- closes #mBody-->
</body>
</html>