JMRI: Names and NamingThis page discusses how JMRI objects are named, how those names are used to reference the objects (hardware and software), and how user-readable names are used.
What's in a name?Why do we need names at all, rather than just references within the code? There are several important uses:
- When working with user input, e.g. typing a number in a field, the code will need to know how to map the user-provided info onto objects. Sometimes the user will want to name objects with arbitrary user names, e.g. "East Lockport Turnout". These can't be known until their mapping to hardware has been made. But other times these will be de-novo identifications that the code must understand, e.g. something that means "LocoNet Turnout 23".
- We imagine that configurations will be stored in XML files, in a symbolic form. Names are a convenient way to connect objects and object references in that kind of configuration.
Items with namesThere are lots of things that might need names:
- Aspects for signals
- Blocks (track segments)
- signal Heads
- Lights (a type of output)
- Power districts and subdistricts
- input Sensors
System and User NamesJMRI users both "system names" and "user names" to reference things.
We want users to be able to call things what they want. Names like "p(24,23)*" are not useful. Every named item will therefore have a "user name", which is an entirely free-form string. You can put whatever you want in there, so long as it's not a duplicate of the name given to something else. For example, you might call a Turnout "West Yard Lead" or "Turnout 32" or "Green Wire from Controller" or whatever.
At the same time, we need a shorthand name, really a unique identifier, to talk about specific objects. This doesn't have to be convenient, but does have to have a clear mapping from name to object and back. For example, we need a very specific way to identify "LocoNet Turnout 23". We call these "system names". JMRI code will map these to and from whatever information the hardware may need.
System Name FormatA system name is formed from a single upper case letter representing the hardware system, followed by a single upper case letter indicating the type, followed by system- and type-specific string. The string is meant to be related to the hardware addressing, but is otherwise unconstrained.
- LT23 - LocoNet Turnout 23.
- CS12 - The 12th C/MRI Sensor (input line).
Hardware system lettersNote that some of these are placeholders, and have no underlying implementation. (Links are to JMRI pages with more information)
- A CTI Acela
- B (reserved for CTI Train-Brain)
- C C/MRI serial
- D SRCP
- E EasyDCC
- F RFID tag readers
- G ProTrak Grapevine
- I Internal, e.g. objects with no associated hardware
- K Maple Systems
- L LocoNet
- M Model railroad layout control buses, of which the first is MERG CBUS
- N NCE (also Wangrow currently)
- O Oak Tree Systems
- P Powerline transmission, e.g. X10 and Insteon
- Q QSI programmer interface
- R RPS system
- S SPROG
- T Lionel TMCC
- U ESU ECoS
- V TracTronics SECSI
- W (reserved for Wangrow, but that's currently still combined with NCE)
- X XpressNet
- Z Zimo MX-1
Device type lettersNote that some of these are placeholders, and have no underlying implementation. Also, there is no guarantee that any given hardware system will ever implement all of them.
- A Audio - an internal software object that holds information about a sound sample to be placed at a specific position in 3d space
- B Block - A software object that keeps track of the contents of a specific block of track
- D iDentity - A software object that holds information about an identity tag that is, typically, attached to a piece of rolling stock. These objects are not system-specific but are Internal objects, hence have system names commencing with ID. The underlying hardware will use Reporter objects to communicate back to JMRI when a specific iDentity object has been seen.
- F signal mast (F is not particularly mnemonic; maybe a mast with two heads looks like an F from the side? All the good letters were taken)
- H signal Head - One part of a signal (which may have multiple heads). Also interpreted to include indicators on control panels that are acting to display signal aspects
- M Memory - As yet, this has no real equivalent in the layout hardware, but is used as a place to store information temporarily and display it on panels, etc.
- L Light - another form of output, used to e.g. control lights on a layout
- P Power manager i.e. layout, district, subdistrict; not all systems distinguish between these, so the device type letter doesn't either. The system-specific part of the name can. For example, the system specific part might be B for main layout power, e.g. LPB or S42 for subdistrict channel 2 on card 4, e.g. LPS42.
- R Reporters - a general purpose mechanism for reporting complicated information from the layout, e.g. locomotive identification from some transponding hardware, RFID tag numbers, etc.
- S Sensors - general purpose input sensors that can generally be either ACTIVE or INACTIVE. This is most commonly used for block occupancy detectors.
- T Turnout - actually a general purpose output on the layout
- X logiX - a set of logic equations used to control the layout
System-specific infoEach different hardware system can specify the "string" that follows the system and type letters. Generally, these are small numbers, but their exact meaning is very system-specific. For more information, please see the specific pages for
"Internal" objects can also be addressed and manipulated, but they don't have a strict
correspondence with some hardware on the layout. For example, if a signal head
is implemented as three different outputs, LT1, LT2 and LT3, the signal head object
might be called IH3.
Naming Conventions For Automated Use
Some higher-level constructs create their own items. For example, a
is really just a collection of
that implements the sensor group logic; there is no specific object in the
program that implements the sensor group. Instead, when the user
creates sensor group "my group", a series of routes with system names like:
are created which implements the group. The sensor group tool knows to look
for routes of this name.
SENSOR GROUP:my group:LS1
SENSOR GROUP:my group:LS2
To make this possible, two informal rules are used:
- Users should not use the ":" or "$" characters in system or user names. Automatic tools should use at least one of these to make sure they don't collide with user-selected names.
- Tools that use this method have their tool name at the start of any system names they create, as "SENSOR GROUP" was used above.
The list of tools currently working this way is:
- SENSOR GROUPS - jmri.jmrit.sensorgroup
- USS CTC - jmri.jmrit.ussctc
- Some devices are not really named, as there's no idea of more than one yet. The DCC programmer is the first example, but there may be others.
- The system name convention doesn't provide an easy way to identify more than one adapter of a given type. E.g. if you're connected to more than one LocoNet, or more than one command station of any single type, that feed separate parts of a single layout, how do you address this?
- Similarly, there's no provision for a single program to deal with more than one layout. If that's needed, we'll have to understand what the program is trying to do.