Software documentation

Development tools

Structure

Techniques and Standards

How To

Functional Info

Background Info

JMRI: Structure of External System Connections

This page is about how JMRI connects to external systems, e.g. DCC systems.

There's a lot of variation within JMRI on this, so you'll have to go through any specific implementation. Specifically, older systems weren't always arranged this way, so existing code may not be a good example.

Basic core is communications code, often a "TrafficManager"

See also the Multiple Connection Update page.

Code Structure

(Needs work) The code for a general type, like "LocoNet connections" or "NCE connections", should be gathered in a specific package right under jmri.jmrix e.g. jmri.jmrix.loconet and jmri.jmrix.nce. This provides a level of grouping, which we may someday want to use for e.g. providing separate updates for specific hardware, while still separating the system-specific code from the system-independent parts of JMRI.

Within that, the code should be separated further by subpackages for:

Additional subpackages can be used grouping various functions as needed.

Normal Operation

The key to normal operation (after start up and before shut down) is a SystemConnectionMemo object that provides all necessary access to the system connection's objects. For example, the LocoNetSystemConnectionMemo provides access to a number of LocoNet-specific objects and LocoNet-specific implementations of common objects. Although some of those (e.g. a SensorManager) might be separately available from the InstanceManager, accessing them from a SystemConnectionMemo allows you to find the consistent set associated with a specific connection. This can be very valuable when working with multiple connections.

Initialization

We don't directly persist the SystemConnectionMemo. This is partly for historical reasons, but it also reflects the level of abstraction: A SystemConnectionMemo is at the level of a "LocoNet connection" or a "NCE connection", and there's a lot of specific information below it to configure one of many possible such connections.

Instead, configuration of the connection is from the bottom up: From the most specific code up to the general. The "Adapter" object connects directly to the system, e.g. managing a serial

"Simple" Initialization Sequence

This section describes the LocoNet implementation of the new (post-multiple) configuration system. This is similar for LocoBuffer, LocoBuffer-USB, PR3, etc connections, but we use the This sequence picks up after the basic startup of the application itself, see the App Structure page for that.

There are several objects involved in startup:

The profile XML file contains a connection element that drives the configuration:

        <connection xmlns="" class="jmri.jmrix.loconet.locobufferusb.configurexml.ConnectionConfigXml" 
                                disabled="no" manufacturer="Digitrax" port="/dev/tty.usbserial-LWPMMU13" 
                                speed="57,600 baud" systemPrefix="L" userName="LocoNet">
            <options>
                <option>
                    <name>CommandStation</name>
                    <value>DCS50 (Zephyr)</value>
                </option>
                <option>
                    <name>TurnoutHandle</name>
                    <value>Normal</value>
                </option>
            </options>
        </connection>
      
Initialization proceeds through multiple steps (click on the diagram to expand it):