Lenz Command Station Poll: How to Collect Data

**Thank you for your interest in the poll !**

The goal is to collect information from **XPressNet Monitor**, which is part of JMRI. If possible, system logs from JMRI could be also collected to give more details about communication processing.

The captured command-response patterns will serve as a reference to create enhancements that can be used in existing testing code to improve stability of JMRI. Captured sequences may also become part of reference developer documentation to improve sustaining of the project.

The primary goal is however to make my "Friday project" of NanoX and DR5000 support better - so I can better understand the differences from Lenz original hardware and what changes are needed in code specific for those system connections.

**Do not be scared** by the length of the page -- there are a lot if pictures which make it so long!

## Hardware

I am primarily interested in data from **some** Command Station and PC interface combinations:

1. **Lenz LZV100** command station, connected through Lenz LI-100, Li-100f or LI-101 **serial** interface.
2. Lenz LZV100 or LZV200 command station, wired to **work with LS100 decoders** and using their **R-S turnout feedback**, so JMRI can see the turnout "moving". The usage of working(!) LS100 R-S feedback is critical in this case.
3. **Lenz LZV200** command station, connected using USB port built into the command station, or LI-USB adapter

## Setup for testing

### Setup JMRI for logging (optional)

This step is for the **brave ones**. It will allow to collect detailed processing data that may provide better understanding of operation. There's a file **default.lcf** in the root of JMRI installation (not userdir, or profiles dir !) that needs to be **temporarily** changed. If your JMRI is installed in **C:\JMRI\4.18**, then the file is **C:\JMRI\4.18\default.lcf**.

**MAKE A BACKUP COPY OF THE FILE !**

Open the file with a text editor (**Wordpad** on Windows, but virtually any text editor that can save **unformatted** .txt files). If your text editor garbles line endings, joins many lines into one long one (as may be the case of **Notepad** on Windows), **do not save the file** and choose a different text editor.

Append the following lines (copy / paste) at the end of the file:

```
log4j.category.jmri.jmrix.lenz=DEBUG
log4j.category.jmri.implementation.AbstractTurnout=DEBUG
log4j.category.jmri.jmrix.AbstractMRTrafficController=DEBUG

```

Please make sure that pasted lines **really start** with "log4j.category", no spaces before. Save the file when done.

This is it ! The added lines will turn on debugging output for existing Lenz support in JMRI. The log will contain timestamps that will allow to correlate with XPressNet monitor log.

If you intend to copy-paste contents of the system log from GUI, use **System Log** tool located in **Help** menu of **PanelPro** window. This will open the System Log window. Please **keep this window open**, maybe minimized; otherwise some early messages may be missing. All the information is logged into *session.log* file - see near the end of this page for how to find it.

### Setup the XPressNet montior

The most important is to collect **logs from XPressNet monitor tool** in JMRI. The tool can be found in XPressNet main menu of **PanelPro** JMRI application (see screenshot,click the picture to enlarge).

In case you're not familiar with the tool, the monitor window looks as in the following screenshot:

Data flowing in or out of JMRI will display in the central area. It is essential to log including **raw data bytes** and **time information**, so that timing can be retained in the JMRI code. **Please check BOTH** "Show raw data" and "Show timestamps" checkboxes below the central monitor's area:

There are two ways how to get data out of the XPressNet Monitor at the end

* Copy/Paste
	+ Click on the messages area.
	+ Press CTRL-A to "select all", then CTRL-C to copy to clipboard
	+ Open a text editor, press CTRL-V to paste clipboard into the text file
	+ Save the file
	+ MacOS users will use probably Command-C, Command-V
* Let XPressNet monitor write the log to a file. Use "**Choose log file...**" button, browse the appropriate folder and **type in** the name of a file that the XPressNet monitor should write into. Then, press "**Start logging**" button:

**Well done !** The XPressNet monitor setup is complete.

**DO NOT CLOSE THE WINDOW.** If you close it, you won't be able to copy/paste the data from it later.

If you have any question to the setup, or the test steps, please e-mail:

```
svatopluk.dedic@gmail.com

```

I can be also reached on Skype as "svatadedic' (CEST / GMT+2 timezone).

## Check the version of your Command Station and LI interface

To correctly analyze the logs, I need the exact make/version of the hardware. **Double-check** the labels on the command station or LI\* interface enclosures - if the log is annotated with an incorrect command station make/version, the results may be misunderstood and lead to incorrect implementation :-(

**Please note down your command station make** (LZV100, LZV200, ...) **and LI interface make** (LI100, LI100F, LI101, ...). In addition, please ask JMRI to display the **sofware version**. In the **XpressNet** main menu of PanelPro, use "**XpressNet System Information**" tool. A window will pop up, with version fields *unfilled*initially.

Press the "**Get System Information**" button, ensure the **XpressNet monitor** window is opened - it will log JMRI's query and station / LI interface responses.

**Please note down** the entries for:

* Command Station
* Software Version
* Interface
* Hardware Version
* Software Version

Or make a screenshot of the window.

## Perform the test !

### Operate Turnouts

Please open the "**Turnout Control**" tool from the main menu of **PanelPro** application. A simple window that allows to control a turnout appears.

Please choose two turnouts from those you use on your layout. Choose them so that:

* one has **odd** number (i.e. System Name XT33)
* the other has an **even** number (i.e. System Name XT36)
* but such numbers, which **do not follow each toher** (so don't choose e.g. XT33 and XT34; XT33 and XT38 is fine, as well as XT34 and XT37)

Enter the first Turnout number into the "Turnout" edit box in the Turnout Control window. Then use buttons "**Thrown (+)**" and "**Closed (-)**" in the **exact** following sequence. Wait a little (1-2 seconds) between the steps. Definitely wait until your switch finishes its job. **Make sure** that the **XpressNet monitor** window is still open.

1. Thrown
2. Closed
3. Thrown
4. Closed
5. Closed
6. Thrown
7. Thrown
8. Closed
9. Thrown

The first two will flip the turnout back and forth to get it to a defined position. The next two will record its movement back and forth from that defined state. The next 4 will record what happes when the turnout wasn't actually moving ("closed" command is sent while the turnout **was** already in Closed position). The last two operations just make it go back and forth again, to provide repeated data.

If find out that you misclicked some button in the sequence, **don't worry**: Just make a note, in the **XpressNet** monitor, that it was needed to restart the test:

* Go to XpressNet monitor window
* Next to "**Add to log**" button, type in a message. Ideally start it with some marker like "-------------", so the message could be "--------- Oops, misclicked. Restarting Turnout test". **Then** click the "**Add to Log**" button

Please **do not clear** the XpressNet window, the log file (selected earlier) will not be cleared and it wouldn't be obvious where the proper test sequence started. Also, if you cleared the XPressNet monitor, and later choose to Copy/Paste the content, the initial sequence from checking SW version wouldn't be there. Just append a message to the log, and go through the sequence again.

### Operate with the other Turnout

Now please enter the **other** turnout's number into the Turnout field, and **repeat the exact sequence above**. If you want, you may note start of the test using the **Add to Log** in the **XPressNet monitor** window. Please **do** make a note, if you misclick in this second sequence with the other Turnout.

**Thank you ! That's all for Turnouts**, please dismiss the Turnout control window, but still leave **XpressNet monitor** opened.

## Optional Tests

These additional tests will improve the data collection. At this moment, I need to address Turnout operations. But you would be extremely helpful, if you could perform a few more actions so the collected communication is more complete.

### Route operation

Applicable **only i**f you **already have** a Route or LRoute defined for your layout which you can easily activate. If you choose to perform this test:

1. Please make a note in the **XpressNet monitor**; ideally note the first turnout operated by the (L)Route, so I can identify start of the sequence.
2. Activate the (L)Route

The sequence of operations will be logged to XPressNet monitor and/or System log.

### Write to a CV

**Safety first !**

Make sure that **no vehicle is on your programming track**. Ideally, the **P, Q** outputs of your Lenz Command Station are not connected at all - or **please** **make sure** that no decoder, stationary or locomotive can be affected by the operation. If you **really want** to write the CV to a real decoder / locomotive, fine - since the log will show how the command station respons 4when the operation is successful: the more situations are logged the better for the code and testing. But you can save time finding a CV to safely manipulate with.

Open up a **Simple Programmer** tool from JMRI's PanelPro menu (see screenshot). The programmer window opens. **Make sure** the **XpressNet monitor** window is still open.

* Please switch it into **Direct byte** mode, if not selected already.

* Enter **222** into the **CV** field. Only if you **really want** to write to a real decoder, please select a **safe CV number** to modify.
* Enter value **55** into **Value** field. When writin to a real decoder, select some **safe value** for the CV
* Press **Write CV** button

The handshake between Command Station and JMRI will be captured in the XpressNet monitor tool.

### Read from a CV

With the same programmer and CV set up, please push **Read CV** button. The XpressNet monitor will, again, capture the messages between JMRI and the command station.

**ALL DONE.** The last thing is to save the log files.

## Saving log contents

#### Log from XpressNet Monitor tool

If you used "**Select a log file...**" button during preparations and pressed **Start Logging** button, the XpressNet log is already saved. If you choose to copy the content manually, open up any text editor, which can save plain text (not Word please ! Use e.g. Wordpad, or Notepad). You can

* select all the text, by pressing **CTRL-A** in the XpressNet window
* Copy (CTRL-C)
* Paste into the text editor (CTRL-V)

Save the result file.

### System log

In the case you **changed the logging settings** and in the JMRI (see setup for testing), and you **want to send system log as well**, there are two approaches:

* Copy contents of system log, or
* Manually copy/paste contents from System Console window.

#### Copy contents of system log file

Use **Locations...** action in **Help** menu of the **PanelPro** application. The *session.log* **full path** should be listed last in the window. Use **Open Log Files Location** to locate the *session.log* file. This file has the debug output contents.

#### Manual copy/paste

For this, you need to have the **System Console** window opened for the whole test; otherwise some early printed messages may be missing from the window. You can then use the same procedure as described for XpressNet monitor:

* select all the text, by pressing **CTRL-A** in the System Console window
* Copy (CTRL-C)
* Paste into the text editor (CTRL-V)

#### Sanitize Log Contents

**Please review** start of the text. There may be listed full file paths on your hard drive. I don't want these - and you should keep those paths confidential, for security reasons. Even though I am not going to share those with anyone, it's safest not to send them anywhere at all. Delete all the contents up to line that contains

```
INFO  - Main initialization done

```

No paths should be printed after this.

## Send the data

Please send the data using **e-mail** to:

```
svatopluk.dedic@gmail.com

```

**Do not send the data to JMRI mailing list** - other users will probably have no interest in barely readable log files.

Please include the following information in the e-mail:

* Your command station exact make and version; i.e. LZV100, version 3.0
* Your LI\* interface make, e.g. Lenz LI100F.
* Whether your system uses **RS-BUS and LS-100** Turnout module for Turnout feedback (Yes/No)
* The information noted in "Check the version of your Command Station and LI interface" section

Attach the log files (or the text file where you pasted the log contents):

* XpressNet monitor log file
* System log file

Please **attach the log files as attachements** to the e-mail message. **DO NOT** paste the text into the e-mail: it will be line-wrapped and almost impossible to read correctly. Some of the log file lines are super-long.

Should you have any questions, please e-mail to the above address.

## Clean up (optional)

If you **altered** the **default.lcf** file, you need to revert the changes. Just replace the file with the backed-up contents. Otherwise your JMRI will extensively log, which costs the disk space and may slow down your JMRI installation.

## **THANKS A LOT EVERYONE WHO READ SO FAR FOR HIS/HER PATIENCE !**

**THANKS MANY MORE TO EVERYONE WHO WILL SEND THE LOG FILES.**