Support: LocoNet® addressing
- General LocoNet Object Types and Addressing: "System Names" and "User Names"
- Addressing for LocoNet Device Programming
General LocoNet Object Types and Addressing: "System Names" and "User Names"
LocoNet® systems provide "general purpose inputs" via LocoNet "Sensors", provide "general purpose outputs" via either LocoNet-connected or DCC-connected "Turnouts", and provide "Reporter zone" numbers via LocoNet "Transponding zones". Each of these object types use independent addressing within LocoNet messaging.
There is a direct relationship between an object's LocoNet address and one of two ways in which JMRI works with the object. The object's JMRI "System Name" has this direct relationship.
Alternately, JMRI allows the user to reference the object using a "User Name", which is a user-defined name for the object. When referencing these objects within JMRI, one can generally use either the object's "User Name" or its "System Name" to reference the object.
Use of these descriptive "User Names" to reference objects within JMRI can simplify development and debugging of JMRI "Signaling" configurations and "Logix Conditionals". JMRI developers suggest that users make use of object "User Names" wherever possible. Additional general information on JMRI "System Names" and "User Names" may be found here.
System Names and LocoNet
JMRI communicates with the individual physical turnouts, sensors, reporters and other physical objects via individual "system names". Each physical object which JMRI interacts with has a unique "system name". A typical JMRI system name is made up of a letter which indicates the connection type, plus another letter which indicates the type of object, plus one or more digits to indicate which specific object is being referenced.
LocoNet system names typically look like "LT5", "LS2013", and "LR535". These three system names represent LocoNet Turnout 5, LocoNet Sensor 2013, and LocoNet Reporter 535, respectively.
It is important to note that JMRI generally treats each unique object "system name" as a separate object. This means that the sensor with system name "LS9" is a separate entity from the objects referred to by the system names "LT9", "LR9", and "L2S9". It is possible that specific LocoNet hardware imposes some specific relationship between various objects with the same address, but JMRI does not assume any relationship between them.
Similarly, where a JMRI installation has more than one simultaneously-active LocoNet connection, JMRI will be configured with differing "prefix" information for each connection. The unique prefixes are used in the JMRI system names to indicate which LocoNet connection the object refers to. "LT5" refers to switch 5 on a system connection with prefix "L", while "L2T5" refers to switch 5 on a different system which has a prefix of "L2". Those two independent system names denote two independently-controlled and independently- controllable turnouts on the two independent communication channels.
JMRI Sensor, Turnout, and Reporter Tables
For user monitoring of these objects, and, as appropriate, user control of these objects, JMRI provides a "table" for each of these object types. These tables list all of the objects of a given type (i.e. "Turnouts") which are known to JMRI at a given time. Each Table shows the System Name, User Name (if assigned) and State of each known object. Additional configuration and comment information may also apply for some object types; where applicable, additional configuration buttons and information fields may appear in the Table on the same line as a given object.
LocoNet "Turnouts" are found in the "Turnout Table", LocoNet "Sensors" are found in the "Sensor Table", and LocoNet "Transponding Zones" are found in the "Reporters Table". Entries to these tables may be made manually by the user, or automatically when JMRI "sees" a LocoNet message which implies an object which is not already in the appropriate table. A sample of a JMRI Sensor Table is shown below.
Saving your changes
JMRI does not remember the Turnout, Sensor or Reporter table entries from a previous JMRI session unless you take specific action to save your information, and unless you take specific action to instruct JMRI to read the saved configuration. (This is generally also true of the information in the other Tables.)
JMRI "Panel files" are used to save the information from the "Tables". A JMRI "Panel file" may also include information needed to display any JMRI "Layout Editor" panels and/or JMRI "Control Panel Editor" panels you have defined (this is the reason the file is called a "Panel file"). Saving a "panel file" may be done from one of the "Tables" windows (i.e. "Turnouts", "Sensors", etc.) by selecting the "File" menu item and then selecting "Store", then either "Store configuration only to File..." or "Store Configuration and Panels to File...".
JMRI provides a few different ways to automatically load a "panel file" at JMRI start-up. The most-commonly used mechanism is via JMRI's "Start Up" "Preferences", which can be accessed via the JMRI "File" menu, then selecting "Start Up". Simply select "Add", then "Open file...", and then select the file (or, if required, multiple files) to be opened at start-up. Then select "Open". It is then necessary to "save" the configuration profile to configure JMRI to use the new settings on next JMRI start-up.
On subsequent JMRI invocations, all start-up actions are invoked, including any "start-up" actions you have defined to "Load" a "Panel File".
If automatic reloading of the table entries is not desired, it is possible to manually read a panel file. Under the JMRI "Panels" menu item, select "Open Panel..." and then locate and select one or more panel files containing the appropriate information. Select the "Open Panels" button to read those files into JMRI.
Note that JMRI panel files are typically specific to a given system connection. If you have configured JMRI for multiple system connections, the panel file will typically be available only for the system connection in which it was created.
Adding an item to the table
From the Tables window, with the "object type" selected in the list at the left ("Turnouts", for example), select the "Add..." button which is found near the bottom of the window. This opens a new window where you may enter the information for the new object. If you are asked for a "Hardware Address", you should not specify a "System Name"; instead you should enter the "address" of the item you are adding - for example, "14" (without the quotes), to specify an object with hardware address "14". The tool will figure out the full "System Name" from the "System Connection" setting and the "Hardware Address" value.
As an example of manually adding a LocoNet turnout, consider adding turnout number 34, and assigning the object the "User Name" "Yard throat 3/4 track switch". This may be done via the "Turnout Table" by pressing the "Add..." button at the bottom of the table, then entering the information shown here.
Activate the "Create" button to add the new entry into the "Turnout Table".
When multiple "connections" are configured in the current JMRI Configuration Profile, the "System Connection" box allows selecting between the connections which are available. JMRI will create a system name using a connection prefix which applies to the selected "system connection".
Because an object's System Name must be unique, the tool will report an error message if you enter information which would duplicate a pre-existing object's System Name.
Addressing LocoNet Turnouts
Digitrax throttles and JMRI use identical numbering for LocoNet turnouts. The "Hardware Address" number JMRI uses to refer to a turnout is exactly the same number as used when using a Digitrax throttle to control a "Switch". Digitrax documentation describes LocoNet turnout numbers as having a range from 1 to 2048. JMRI uses a "System Name" to refer to the hardware object, and the "System Connetion Prefix" and "object type character" must be used in conjunction with the "Hardware Address" number to make a complete System Name for a LocoNet Turnout.
For example, if a JMRI is configured for a single LocoNet connection, and that connection has the default "System Prefix" of "L", and a turnout on that LocoNet connection has an address of 12, then the associated JMRI System Name would be "LT12", where "L" is the "system connection prefix", "T" represents a "Turnout" object type, and "12" is the "Hardware Address" of the turnout.
As another example, if a JMRI LocoNet connection has a user-defined system connection prefix of "GRAPE", and a turnout on that connection has an address of 12, then the associated JMRI System Name would be "GRAPET12", where "GRAPE" is the "system connection prefix", "T" represents a "Turnout" object type, and 12 is the "Hardware Address" of the turnout. Note that if JMRI is configured for two connections, one with system connection prefix "L" and the other with system connection prefix "GRAPE", the JMRI system name "LT12" refers to a turnout object which is considered entirely separate from the turnout referred to by the object with system name "GRAPET12".
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 the "known state" of an existing entry in the Turnout Table or JMRI creates a new entry if one does not already exist. When JMRI automatically adds a Turnout Table entry in this way, it does so with a blank "User Name". Users may update the "User Names" in the Turnout Table. As noted above, it is helpful to save your Turnouts Table changes so that you may re-load those updates into JMRI at a future time.
The Turnout Table provides a useful snapshot of the current state of all Turnouts "known to JMRI", 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 JMRI Turnouts page.
JMRI "Lights"
JMRI provides an object-type called "Lights". For some DCC systems, "Light" objects are defined and addressed separately from "Turnout" objects. LocoNet does not define a separate "Light" object. To support "light" objects on LocoNet connections, JMRI maps its "Light" objects into equivalent LocoNet "Turnout" objects.
This means that changing the state of a JMRI "Light" object with System Name "LL123" will actually modify the LocoNet turnout which corresponds to the JMRI turnout with System Name "LT123".
Addressing LocoNet Sensors
Digitrax throttles and JMRI use identical numbering for LocoNet sensors. The "Hardware Address" number JMRI uses to refer to a sensor is exactly the same number as is reported by some Digitrax throttles which can monitor for and display information from LocoNet sensor state messages. Digitrax documentation describes LocoNet sensor numbers as having a range from 1 to 4096. JMRI uses a "System Name" to refer to the hardware object, and the "System Connection Prefix" and "object type character" must be used in conjunction with the "Hardware Address" number to make a complete System Name for a LocoNet Sensor.
For example, if a JMRI is configured for a single LocoNet connection, and that connection has the default "System Prefix" of "L", and a sensor on that LocoNet connection has an address of 12, then the associated JMRI System Name would be "LS12", where "L" is the "system connection prefix", "S" represents a "Sensor" object type, and "12" is the "Hardware Address" of the Sensor.
As another example, if a JMRI LocoNet connection has a user-defined system connection prefix of "GRAPE", and a sensor on that connection has an address of 12, then the associated JMRI System Name would be "GRAPES12", where "GRAPE" is the "system connection prefix", "S" represents a "Sensor" object type, and "12" is the "Hardware Address" of the sensor. Note that if JMRI is configured for two connections, one with system connection prefix "L" and the other with system connection prefix "GRAPE", the JMRI system name "LT12" refers to a sensor object which is considered entirely separate from the turnout referred to by the object with system name "GRAPES12".
The simplest way to find the correct number for a given Sensor is to open a JMRI "LocoNet monitor" window, and watch the window while causing a change to be reported by the sensor. Look for an entry which shows a changing state which matches the activity. For sensor which is used to detect block occupancy, remove all detectable equipment, then place a locomotive onto the chunk of track which is monitored by the block occupancy detector. Watch the messages in the monitor for a sensor message. Then remove the equipment from the block to see the sensor change state again. Confirm that the sensor number is consistent.
The message shown in the LocoNet Monitor window will typically look something like this:
Sensor LS514 () is High. (BDL16 # 33, DS2; DS54/DS64 # 65, SwiA/S1).
This message is interpreted to mean that The sensor with "System Name" of "LS514" and an undefined (empty) "user name" is currently "High". In this particular case, the sensor is being used to report block occupancy detection, and "High" means that the block is "occupied".
The Sensor Table
The JMRI Sensor Table shows a list of all Sensors of which JMRI is aware. Every time JMRI sees a LocoNet message which specifies a Sensor, JMRI updates an existing entry in the Sensor table or creates a new Sensor entry if one does not already exist. Each Sensor in the table can be assigned a "User Name". As noted above, it is helpful to save your Sensor Table changes so that you may re-load those updates into JMRI at a future time.
The Sensor Table also 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 JMRI Sensors page.
Addressing LocoNet Transponding Zones
Digitrax Transponding is handled via the Reporter mechanism in JMRI. Reporters gather information from the layout and make it available when it changes. JMRI typically refers to LocoNet Reporters using the System Name LRx where L is the system connection prefix for a LocoNet connection and x is a number which corresponds to a detection zone. The system connection prefix may be different when multiple System Connections are configured.
Within JMRI, Transponding Zones are numbered sequentially from 1 to 4096. This differs from the way Digitrax throttles report Transponding zones. If the "Find" feature is activated on a DT300x, DT40xx, or DT500x throtte, the display will report zones between 0 and 4095. When comparing JMRI transponding zone numbers and Digitrax throttle-reported zone numbers, the JMRI transponding zone number is always one higher than the number reported by the Digitrax throttle.
Current BDL16x hardware implements only odd-numbered Transponding zones. The first Transponding zone of a BDL16x board is reported as JMRI 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:
| BDL16x 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 | |
BXP88 devices implement sequential Transponding zone numbers. The first Transponding zone of a BXP88 is reported as JMRI reporter number (8 * (board address -1)) + 1, and the last Transponding zone of a BXP88 is reported as JMRI reporter number (8 * (board address -1)) + 8. This numbering happens to match the BXP88 block occupancy Sensor numbering. If a BXP88 detection section reports its block occupancy via JMRI's LS45, then the transponding zone for that section will be via JMRI's LR45.
BXP88 Reporter numbering is summarized in the table below:
| BXP88 Board ID | Detection Section | Reporter Number | Detection Sensor |
| 1 | 1 | LR1 | LS1 |
| 2 | LR2 | LS2 | |
| 3 | LR3 | LS3 | |
| ... | |||
| 8 | LR8 | LS8 | |
| 2 | 1 | LR9 | LS9 |
| 2 | LR10 | LS10 | |
| 3 | LR11 | LS11 | |
| ... | |||
| 8 | LR16 | LS16 | |
| 3 | 1 | LR17 | LS17 |
| 2 | LR18 | LS18 | |
| 3 | LR19 | LS19 | |
| ... | |||
| 8 | LR24 | LS24 | |
| ... | |||
| 256 | 1 | LR2040 | LS2040 |
| 2 | LR2041 | LS2041 | |
| 3 | LR2042 | LS2042 | |
| ... | |||
| 8 | LR2048 | LS2048 | |
BXPA1 devices implement a single Transponding zone. That zone is numbered as being equal to its Board ID value. For a BXPA1 with Board ID set to N, JMRI will typically report via reporter "LRN". Note that BXPA1 block occupancy is reported via a different number than the BXPA1 transponding zone.
BXPA1 Reporter numbering is summarized in the table below:
| BXPA1 Board ID | Detection Section | Reporter Number | Detection Sensor |
| 1 | 1 | LR1 | LS1 |
| 2 | 1 | LR2 | LS3 |
| 3 | 1 | LR3 | LS5 |
| 4 | 1 | LR4 | LS7 |
| 5 | 1 | LR5 | LS9 |
| ... | |||
| 1024 | 1 | LR1024 | LS2047 |
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". You may manually enter Reporter Table entries when you know the correct System Name for the reporter; it will be updated whenever a LocoNet message for that reporter is seen.
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 a transponding-enabled locomotive through all transponding-capable zones. It may be convenient to fill in a "User Name" in the JMRI Reporter Table at the time when the Locomotive first enters each Transponding zone. As noted above, it is helpful to save your Reporters Table changes so that you may re-load those updates into JMRI at a future time.
Additional information on Reporters and the Reporter Table may be found at the main JMRI Reporter page.
Addressing for LocoNet Device Programming
JMRI's LocoNet implementation makes use of a variety of other LocoNet-specific addressing schemes for programming LocoNet-based devices.
Device "Board ID"
Some LocoNet-based devices may be configured with a "Board ID" number which allows computer-based device programming and often influences which LocoNet addressing a device uses. Not all LocoNet devices have "Board ID" numbers.
For example, a Digitrax DS64, connected on the LocoNet connection "L", and set for the "Board ID" 2 will default its outputs to be controlled by LocoNet turnouts at addresses 5 thru 8. Within JMRI, the turnouts would be controlled by System Names LT5, LT6, LT7, and LT8. When properly configured, the DS64's inputs will default to act as LocoNet "General Sensor" values at sensor addresses 9 thru 16 (and JMRI LS9 thru LS17), or as LocoNet "Turnout Feedback" values for turnout addresses 5 thru 8.
JMRI requires use of Board ID value when configuring "Op Switch" values in BDL16x, DS64, PM4x, and SE8C devices. This allows the JMRI device programming mechanisms to program only a single device, selected based on the device's Board ID value.
NOTE - Board ID values have independent addressing ranges for each device type. Board ID values for DS64 devices are independent from Board ID values for BDL16x devices, Board ID values for PM4x devices, and Board ID values for SE8C devices. You may have one LocoNet which uses Board ID 2 for a PM42 device and a BDL16x device and a DS64 device and a SE8C device. In this case, JMRI's device configuration tools will be able to configure the devices independently. But the sensor, turnout, reporter, etc. objects of the devices may overlap each other. Be careful to choose Board ID values for each device such that no two devices implement addressed objects which overlap addressed objects of the same type but implemented on another LocoNet device.
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 (non-Digitrax) devices implement System Variables (SVs).
It is believed that Digitrax hardware does not make use of SVs, so users who only have LocoNet hardware produced by Digitrax may skip this section.
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 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.
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.CV
NumberPrior
ContentValue
WrittenMasked
ValueNew
ContentCV1^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 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 |
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 PM4, BDL168, SE8c and DS64 boards use a special messaging protocol to program their Op Switches. JMRI supports this mode in Roster-based programming, so you can treat these types of boards in much the same way as you treat mobile decoders in your locomotives - you may program them using the JMRI "Symbolic" programmers (i.e. the Roster).
Within the JMRI "Symbolic" programmer, the "decoder address" specifies the Board ID number assigned to the device being programmed. Since the programmer uses the Board ID number, it is not necessary to re-wire your LocoNet when programming these devices. The individual "Op Switches" are referenced using a designator which specifies a "device type number" and the OpSw number, with the two numbers separated by a ".". For example, a CV numbered as "113.7" is a reference to a BDL16x device (i.e. 113), OpSw 7. You may ignore the "device type number" when referencing CV numbers shown in the JMRI "Symbolic Programmer".
Addressing "Op Switches" in Digitrax command stations
(The following was first fully available in JMRI 4.9.7. Versions before that may not be complete).
Digitrax command stations use a special messaging protocol to program their Op Switches. JMRI supports this mode in Roster-based programming, so you can treat these command stations in much the same way as you treat mobile decoders in your locomotives - you may program them using the JMRI "Symbolic" programmers (i.e. the Roster).
Within the JMRI "Symbolic" programmer, the "decoder address" is ignored, since there can only no more than one command station on a given LocoNet at a given time. The individual "Op Switches" are referenced using a designator which specifies a "command station OpSw" access type and an Op Switch number, with the two parts of the designator separated by a ".". For example, a CV numbered as "csOpSw.007" is a reference to a "command station OpSw" numbered "7".
LocoNet® is a registered trademark of Digitrax, Inc.
