JMRI: Maple Node Configuration
Maple Systems makes touch screen HMI (Human Machine Interface) panels that can have application to model railroading. In particular, these touch screen HMI panels can serve as hi-tech substitutes for fascia panels on a model railroad layout. This Maple-to-JMRI implementation supports multiple identical HMI panels that can be plugged in at various locations around the layout and used to control and display items related to that location. Each HMI panel has a built-in microcomputer that can be programmed (using a programming package supplied by Maple Systems) to display any number of user selectable displays. It is envisioned that after plugging in his/her panel, the model railroader will select that display appropriate to his/her current location, allowing the panel to serve as a communication device directly into JMRI. After completing tasks at a location, the model railroader will unplug the panel and move with it to another location, etc. Multiple HMI panels operating simultaneously are supported.
The "coil bits" in the Maple HMI panels are used to communicate with JMRI. In this Maple-to-JMRI implementation, all panels use the same address space and have exactly the same input and output bit assignments. The first 1000 coil bits are reserved for configuration as Sensors. Sensors are referred to as "Input Bits" and are used to set JMRI Sensors according to status bits (coil bits) in your Maple HMI panels. Therefore, Sensors pass information from configured HMI panels to JMRI. The next 8000 bits are reserved for assignment as "Output Bits" and are used to send the current settings of Turnouts and Lights to the Maple Panels.
Communication between JMRI and Maple HMI Panels
Maple communications work by polling. Each panel is polled separately, and the results of the polls are ORed together to set Sensors. Therefore if a Sensor is ACTIVE (Maple "1") in any panel, it is set ACTIVE in JMRI. If a Sensor is INACTIVE (Maple "0") in all configured panels, then it is set INACTIVE in JMRI. Panels are polled in the order that they are configured. Note: The Maple poll command allows a maximum of 99 bits to be requested with each poll command, so if more than 99 input bits are configured, multiple poll commands will be needed for each panel.
After all panels have been polled, the status of output bits is sent to the panels. Output bits are sent in "Broadcast Mode" so all panels can receive the bits at the same time. Broadcast Mode is indicated by an HMI Station Address of "0". Output bits begin with an HMI coil bit address of "1001". All configured output bits are sent, regardless of if the bit is assigned or not. Note: The Maple write command allows a maximum of 99 bits to be written with each transmit command, so if more than 99 output bits are configured, multiple transmit commands will be needed. Keeping the number of configured output bits as low as reasonable will reduce the number of transmit commands that must be sent.
Configuring a new Maple Panel
A new Maple Panel (a "Maple Node") is configured by specifying its HMI Station Address, specifying timeout times for polls and sends, entering the number of input and output bits, and clicking the Add Panel button. HMI Station Address is unique to each HMI panel, the other items are the same for all panels. Each item is described below:
- HMI Station Address - This is the address used by JMRI to poll the panel. Each panel must have a different HMI Station Address. Addresses of 1 through 99 are allowed. The addresses need not be consecutive. Panels need not be configured in numerical order.
- Poll Reply Timeout Time - This is the time (milliseconds) to wait for a response after issuing a poll command before going on to the next command in the communication process. The value displayed is the current timeout time, or, if this is the first panel to be configured, the default timeout time. Changing it will change the timeout time for all panels. This time should be set to the smallest number that gives reliable communications between the computer and JMRI. Note: When a panel is configured, but not plugged in (not communicating), it will timeout. This is the expected behavior when a user is moving a panel between locations.
- Send Delay Time - This is the time (milliseconds) to wait after issuing a broadcast write command before going on to the next command in the communication process. The value displayed is the current send delay time, or, if this is the first panel to be configured, the default send delay time. Changing it will change the send delay time for all panels.
- Number of Input Bits - This is the number of input bits that will be polled when each HMI panel is polled. Values of 1 through 1000 are allowed. The number of input bits is forced to be the same for each panel, so if this number is changed when adding or editing any panel, it is changed for all panels. Because of the 99 bit limit in Maple polling requests, multiple poll commands will be required if this number is greater than 99. So keeping this number to the lowest reasonable value will result in faster communications.
- Number of Output Bits - This is the number of output bits that will be sent in broadcast mode at the end of each polling cycle. Values of 1 through 8000 are allowed. The number of output bits is forced to be the same for each panel, so if this number is changed when adding or editing any panel, it is changed for all panels. Because of the 99 bit limit in Maple write commands, multiple write commands will be required if this number is greater than 99. So keeping this number to the lowest reasonable value will result in faster communications.
Important: Always check the messages in the Notes box after each operation! That's where success or errors will be reported.
Very Important: Remember to save your Maple Panel Node configuration information to disk after making changes. Use the Save button at the bottom of the Preferences window.
To change any of the four common parameters (poll reply timeout time, send delay time, number of input bits, and/or number of output bits), enter the HMI Station Address of any configured panel, click Edit Panel, make the desired parameter changes, and click Update Panel. This changes the parameter(s) in all configured panels.
To see a list of the HMI Station Addresses of all configured panels, select List Assignments in the Maple menu, and pull down the Nodes popup menu.
To change the HMI Station Address of a previously configured panel, enter the HMI Station Address of the panel, click Delete Panel, confirm the deletion, enter the new HMI Station Address, and click Add Panel. HMI Station Addresses cannot be changed via Edit.
If you add a Sensor with a system name that addresses a coil bit beyond the configured number of input bits, the Sensor will be added, and a Configuration Warning message will be issued. There is no way to access a Sensor that corresponds to an HMI coil bit outside the range of configured bits. So if you get a Configuration Warning message, you should either change your configuration's Number of Input Bits or delete the Sensor.
If you add a Turnout with a system name that addresses a coil bit outside the configured range of output bits, the Turnout will be added, and a Configuration Warning message will be issued. The configured range of HMI bit addresses is 1001 through 1000 + the number of output bits, corresponding to JMRI addresses of 1 through the number of output bits. There is no way to write to a Turnout that corresponds to an HMI coil bit outside the range of configured bits. So if you get a Configuration Warning message, you should either change your configuration's Number of Output Bits or delete the Turnout.
JMRI will refuse to create a Light if it doesn't correspond to the configured address range for output bits (see above).