JMRI® connects to...
Digitrax LocoNet®
Supported Hardware
Devices, command stations, networks, and protocols:
Applications
By the community of JMRI.org:
Tools
JMRI tools for working with your layout:
Layout Automation
Use JMRI to automate parts of your layout and operations:

JMRI Help:

Contents Index
Glossary FAQ

Donate to JMRI.org

JMRI LocoIO Programmer

The preferred method to program a LocoIO board since JMRI 3 is using DecoderPro with the dedicated Public_Domain_HDL_LocoIO Decoder Definition. See full instructions below.

A LocoIO board is a DIY stationary interface to LocoNet for inputs (fascia pushbuttons, turnout feedback or occupancy sensors) and outputs (fascia indicator LEDs, signal LED's, turnout motors etc.). The original LocoIO design by John Jabour was further developed by Hans Deloof from Belgium.
A typical board contains 16 signal pins, also called channels or ports. Each port can be individually programmed as an input or an output, and to perform a number of different things (depending on the module's hardware and firmware (PIC) version:

Inputs:

Outputs

Since LocoIO rev 1.49

See the Cheat Sheet included in the DecoderPro LocoIO Programmer for further details.

The ports are configured via LocoNet messages, but the DecoderPro Programming interface takes care of many technical details. Documentation is included below and in the decoder definition file.

LocoIO Programmer via Roster

Since JMRI 4.21.2

The Public_Domain_HDL_LocoIO Decoder Definition in the "Public Domain and DIY" category supports set-up of a wide range of LocoIO devices up to LocoIO/LocoBooster/LocoRCD/LocoServo rev 1.54 hardware since 2020.

To use the current LocoIO Programmer follow these steps:

  1. Turn on the layout and power up the LocoIO hardware. No jumpers or buttons on the LocoIO need touching in order to preceed.
  2. Open DecoderPro or the Roster menu option in PanelPro.
  3. In the Decoder Installed box, navigate to "Public-domain and DIY" > "Hans Deloof LocoIO".
  4. Looking at your hardware, select the correct PIC programmer firmware version from the list. It often is labeled on the biggest IC chip. If your version is not in the list, select the first higher one. In this example we pick "LocoIO v1.53":
    Screenshot LocoIO Config step 1
  5. On the right of the Create New Loco pane, enter a name for this module, eg. "LocoIO 81/1 rev 1.53", and fix the ultra-long decoder DCC address suggested. We chose 81, the factory default board address:
    Screenshot LocoIO Config step 2
    Click [Save] and close the Create New Loco pane.
  6. You will see the new entry appear in the Roster.
    Select it, make sure to select Programming on Main, and click [Program]:
    Screenshot LocoIO Config step 3
  7. On the Basic tab, enter the actual LocoIO Main Address and Sub-address, "81" and "1" respectively in our example:
    Screenshot LocoIO Config step 4
  8. Next, go to the Roster Entry pane, click [Save to Roster] and close & reopen the LocoIO definition from the Roster to update the actual decoder address:
    Screenshot LocoIO Config step 5
  9. Returning to the Basic tab, click [Read full sheet]. If a LocoIO is found at the address, its firmware version is displayed (the Monitor LocoNet window will show more precise information regarding the firmware).
  10. Warning: If you wish to change the address of a LocoIO board, you MUST first ensure that ONLY a single LocoIO-based board is connected to the LocoNet, as the address is set via a broadcast message.
    If you Write CV2 and CV3 on the CVs tab or press [Write All] from the Basic tab, ALL LocoIO's on your LocoNet will be reprogrammed with the same new address.

  11. Screenshot LocoIO Config step 6

  12. Screenshot LocoIO Config step 7

  13. Screenshot LocoIO Config step 8a

  14. Screenshot LocoIO Config step 8b
  15. After Read All, many ports will show a Mode selected. Due to the complexity of the LocoIO memory DecoderPro can't figure out some choices, so you will have to assist at this point for those ports that still show "Port not in Use". At least you will notice the numbers already changed. For example on Port 4 the number in the Config field reads "95":
    Screenshot LocoIO Config step 9a
  16. Turn to the Cheat Sheet tab reference, in the Config column look up "95". It's is a Block Detector - Active High:
    Screenshot LocoIO Config step 9b
  17. Return to the Ports tab and in the Port 4 Mode combo, pick "Block Detector - Active High" (either odd or even address, will correct automatically later on):
    Screenshot LocoIO Config step 9c
  18. After clicking [Read changes on sheet]:
    Screenshot LocoIO Config step 9d
  19. After fixing all mode combo's that are not "0", once again click [Read full sheet] to update all fields and inspect the LocoIO configuration. Scroll down to see more ports:
    Screenshot LocoIO Config step 10
  20. Inputs allow setting up to two more actions carried out when the pin goes to ON. You can set the action type and the address on the right hand side of the LocoIO programmer pane as shown here. See the HDL documentation for examples and further information:
    Screenshot LocoIO Opcode Config
  21. A LocoBooster module will show several special options:
    Screenshot LocoBooster Config pane

Third Party info

LocoIO Programmer 2 (no longer supported)

Screenshot of LocoIO Configuration Tool v2 (deprecated)

The following entry is only shown as reference for JMRI versions before 3.0.

You can still use it for the original boards, but consider switching over to configuring your LocoIO boards with the current programmer, documented above.

Version 2 was written by John Plocher for JMRI release 1.8 and only dealt with SV1 & SV2 (address/subaddress) and SV3-SV50 (primary Mode, Value1 and Value2 for ports 1-16). In particular, it did not handle SV0 (board level configuration), SV51-SV98 (alternate Opcodes) or SV101-124 (servo config).

Available options:

LocoIO Programmer 1 (no longer supported)

Screenshot of LocoIO Configuration Tool v1 (deprecated)

The first LocoIO programmer was part of JMRI 1.x. It provided a table-based interface for configuring John Jabour's LocoIO board, a powerful component for building CTC boards and control panels. (More information on the board is available at http://www.locobuffer.com/LocoIO/LocoIO.htm)

The LocoIO programmer v1 used a table to represent the configuration of each channel.

The "Action" column is used to select how the channel/port behaves. Click in a cell to be given a menu of available choices. Currently, the choices are:

"Toggle switch controls turnout"

Generate a OPC_SW_REQ to close/throw a turnout when a toggle switch changes state. When the input goes high, a "close" command is sent; when the input goes low, a "throw" command is sent. The channel configuration value is 0x0F.

"Input low flips turnout"

Generate a OPC_SW_REQ LocoNet message when the input goes low. This is intended for use with a momentary pushbutton. The command sent will alternate the position of the addressed turnout or signal; if "close" was last sent, a "throw" will be sent now and vice-versa. The channel configuration value is 0x2F.

"Input high flips turnout"

Generate a OPC_SW_REQ LocoNet message when the input goes high. This is intended for use with a momentary pushbutton. The command sent will alternate the position of the addressed turnout or signal; if "close" was last sent, a "throw" will be sent now and vice-versa. The channel configuration value is 0x6F.

"Status message sets output"

Drive an output from OPC_INPUT_REP input status messages on the LocoNet. The output goes high when an "input high" message is received, and goes low when an "input low" message is received. These messages are also used for block occupancy status; the output will go high when the block is occupied, and low when its empty. The channel configuration value is 0XC0.

"Turnout close cmd sets output"

Drive an output on the LocoIO board from received OPC_SW_REQ commands. The channel configuration value is 0x80. This adjusts the address field to look for a command that sets the turnout "closed".

"Turnout throw cmd sets output"

Drive an output on the LocoIO board from received OPC_SW_REQ commands. The channel configuration value is 0x80. This adjusts the address field to look for a command that sets the turnout "thrown".

The "Hex Value1,Value2" column sets the address that the LocoIO board will use for LocoNet communications. This contains a hexadecimal representation of the two configuration values described in John Jabour's LocoIO programming guide. You generally won't need to figure out these addresses, as the capture buttons will find them for you.

The Read button reads from the LocoIO board via the LocoNet and shows the current configuration for that pin. The Write button stores the current settings to the LocoIO board.

The Capture button provides an easier way to find a needed LocoNet address. Configure the input and output for a particular pin, then press the Capture button. The address in the next LocoNet message of the right type will be put in the address column.

For example, if you have a channel set to act when a "Turnout closed status message" is received, press the Capture button and use your throttle to command the correct turnout Closed.

As another example, if the channel is configured to send a "Send throw turnout command", press the Capture button and use your throttle to command the correct turnout Thrown.

At the bottom of the table are some general controls. The LocoIO address field sets the address of the board being programmed. LocoIO processors are sent with an address of 1051 programmed; see below for how to change that. Address "0" is a global address which any LocoIO board will respond to; make sure you have only one connected when you use that!

The Set address button will use the global address to configure a specific address into a LocoIO board. Again, make sure you have only one connected.

The Read All and Write All buttons read or write all of the channels, and are just a convenience.

Status messages during capture/read/write are displayed at the bottom of the window. If no response is heard from the LocoIO unit, the operation will be retried until it succeeds or until you close the window.