Support: LocoNet® addressing
Adding an item to the table
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.
Here's a summary, split up for outputs (eg. Turnouts) and inputs (eg. Sensors):
|In/Out||Entry||Meaning||makes System Name||Mask||Equivalent||Minimum||Maximum|
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 SensorsInside 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 HiThe 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,
number = 2 * (turnout number - 1) + 1
For example, the aux input associated with turnout 81 has
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.
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|
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:
- nnnn, e.g. 12345 - Like regular CVs, this is the format to read and write an entire byte.
- 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.
- 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.
CV1^01 0x55 0x22 0x01 0x23 CV1^01 0x54 0x22 0x01 0x22 CV1^0F 0x55 0x33 0x03 0x53 CV1^F0 0x55 0x33 0x03 0x53 CV1^33 0xF0 0x77 0x30 0x37
SV version 1 board addressingIn 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:
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, except you specify LOCONETSV1MODE.
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.
Addressing Op Switches in Digitrax boards
(The following was first fully available in JMRI 4.9.7. Versions before that may not be complete).
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.
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:
- 0x70 - 112 - PM4
- 0x71 - 113 - BDL16
- 0x72 - 114 - SE8
- 0x73 - 115 - DS64
LocoNet® is a registered trademark of Digitrax, Inc.