Support: LocoNet® addressing

LocoNet® 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.

Addressing LocoNet Turnouts

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.

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.

The Turnout Table

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".

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.

Additional information on Turnouts and the Turnout Table may be found at the main Turnouts page.

Addressing LocoNet Sensors

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.

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:

   General sensor input report: contact 161 (DS54 switch 81 Aux input) (BDL16 11,1) is Hi 
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.

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 ":"
So for a Sensor on board 11, channel 1 you would enter into the Hardware Address field : 11:1

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

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

For example, the switch input associated with turnout 12 has number:

number = 2 * ( 12 - 1 ) + 2 = 24

The Sensor Table

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".

The Sensor Table provides a useful snapshot of the current state of all known Sensors.

Additional information on Sensors and the Sensor Table may be found at the main Sensors page.

Addressing Transponding

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 LRx where x is a number which corresponds to a detection zone.

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 (1 +(board address -1) * 16). The second Transponding zone of a BDL16x board is reported as Reporter number (1 +(board address -1) * 16) + 2.

Reporter numbering is summarized in the table below:

Board Address Zone Reporter Number
1 A LR1
B LR3
C LR5
D LR7
E LR9
F LR11
G LR13
H LR15
2 A LR17
B LR19
C LR21
D LR23
E LR25
F LR27
G LR29
H LR31
3 A LR33
B LR35
C LR37
D LR39
E LR41
F LR43
G LR45
H LR47
...
256 A LR4081
B LR4083
...
H LR4095

The Reporter Table

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".

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.

Additional information on Reporters and the Reporter Table may be found at the main Reporter page.

Addressing LocoNet device System Variables (SVs)

(The following was first fully available in JMRI 4.1.2. Versions before that may not be complete).

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

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.

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:

SV version 1 board addressing

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:
Old
Style
JMRI
Number
10/1 10
83/1 83
83/2 339
83/0 -173
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!

Using this in a DecoderPro "board" definition

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:
    <programming direct="no" paged="no" register="no" ops="no">
        <mode>LOCONETSV2MODE</mode>
    </programming>

LocoNet SV Version 1 protocol is the same exception you specify LOCONETSV1MODE. For more information, see the schema definition file.

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.

LocoNet® is a registered trademark of Digitrax, Inc.