Skip to main content

DecoderPro® Manual

Setup JMRI

Getting Started

Using DecoderPro

DecoderPro® Programming Modes

The Basic Programmer

The Comprehensive Programmer

DecoderPro® Debug Menu

Virtual Sound Decoder

Back

Manage VSD Locations

The Manage VSD Locations window provides a consolidated location to manage and set the apparent physical location of sounds for trains using Virtual Sound Decoder.

The Manage VSD Locations window has four tabs: Reporters, Blocks, Operations Locations, and Listeners. Each tab shows a list of objects, each with a check-box to enable/disable use (for VSD purposes, not for other JMRI purposes), and entry cells for X, Y, and Z location coordinates.
Reporters
Manage Reporter Locations

The Reporters tab shows a list of all currently defined Reporters. This is intended for use with Digitrax Transponding or other similar locomotive tracking hardware systems.

Blocks
Manage Block Locations

The Blocks tab shows a list of all currently defined Blocks. This is intended for use with Digitrax Transponding or other similar locomotive tracking hardware systems.

Operations Locations
Manage Operations Locations

The Operations Locations tab shows a list of all Locations defined within the JMRI Operations system.

Listeners
Manage Listener Locations

The Listeners tab shows the location of the Listener in the VSD sound system. The Listener position has two additional measurements: the Bearing (angle clockwise from the Y axis) and Azimuth (angle up or down from the X/Y plane) which together describe which way the Listener is facing.

Location Following

With input from locomotive tracking hardware, Virtual Sound Decoder is able to move the apparent source of the locomotive sound to follow the locomotive's position on the layout.

Location Following Setup
To enable location following you will need a hardware method of tracking the locomotive's position on the layout. VSD currently supports the following tracking systems: If you have one of the systems noted as "not tested", and would like to help with testing and debug of this feature, please contact me on the JMRI users Groups.io group. More systems will be added in the future. To enable VSD Location Following, follow these steps:
  1. Follow the directions appropriate to your hardware system for setting up Reporters.
  2. Select Debug->Virtual Sound Decoder->Manage VSD Locations
  3. In the dialog, set X / Y / Z coordinates for each reporter you wish to use for VSD location following. Uncheck the "Use Location" box for Reporters you do not wish to use for VSD tracking.
  4. Click "Save" to store the new values.
  5. Save your configuration either in a config file or as part of a Panel

Note: Reporters are not added to the Manage VSD Locations "live". If you add new Reporters, you must close and re-open the Manage VSD Locations window to make the new Reporters appear.

Coordinate System

The VSD Locations system uses a standard "right handed" Cartesian coordinate system, where a location is defined by a combination of distances along an X, Y, and Z axis. The Origin, or center of the coordinates can be in any convenient location, such as the center of the room, a corner of the room, or a corner of the layout.

The X / Y / Z location values can be in any unit you choose, including an arbitrary relative scheme, as long as you are consistent. By default, positive X is to the space's right, positive Y is "forward", and positive Z is "up". Negative values are left, behind, and down, respectively. Alternately you may prefer to think of +X as "East", +Y as "North", and +Z as "up".

Note: The coordinate system can be rotated in any way that makes sense to the user. If it suits the railroad's arrangement better, +Y could be "East", +X "South", and +Z "Up". It is not recommended that the Z axis direction be changed however, unless your operators are accustomed to hanging from the ceiling.

A convenient system for a typical rectangular room-sized layout would be to place the origin at the near corner to the guest's left as the guest stands in the entry door, or the "bottom left" corner of the layout's track plan map, and with Z=0 at the layout's lowest nominal track elevation for the "live" part of the layout. This system ensures that all locations used will have positive X / Y / Z values.

Listener Location

If you do not specifically set the Listener location and orientation, the Listener by default will be at (0, 0, 0) and facing straight ahead along the +Y axis (bearing 0.0 degrees / azimuth 0.0 degrees). To set a different Listener location and/or orientation, go to the Listeners tab and set the X / Y / Z coordinates of the Listener's location. The coordinates and units must be the same as those used for the Reporters.

The Bearing and Azimuth values set the orientation of the Listener, or the direction the Listener is facing. Bearing is measured clockwise from the +Y axis. Azimuth is measured up (or down if negative) from the X/Y plane. Both measurements are in units of degrees of angle. For example, a Listener standing at the Origin (0, 0, 0) and facing "West" and halfway "up" would have a Bearing of 270 and an Azimuth of +45.

Using Locations

When you have followed the above setup steps, launch the VSDecoder Manager window, create a VSDecoder and run the locomotive. As your locomotive moves around the layout, the sound will follow the locomotive's reported position.

Note: The sound will appear to "jump" from location to location as the locomotive's reported location changes. This effect will be smaller with additional and more closely spaced reporters.

Location Following using JMRI Operations

If you do not have a hardware tracking system, you can use the JMRI Operations feature to enable a rudimentary form of location following.

To set the Operations locations:

  1. Select Operations->Settings
  2. Select Tools->Options
  3. Check the "Enable physical locations for Virtual Sound Decoder" option, and save the changes.
  4. Create Operations Locations within JMRI Operations
  5. Launch the Manage VSD Locations window
  6. Set the locations of the defined Operations Locations.

To use Operations for location following, assign the specific locomotive to the train, then select the train in the locomotive's VSDecoder Options pane. When you MOVE the train in Operations, the sound will move to the next location on the Route.

For more information on Operations, see the JMRI® Operations User's Guide

Advanced Location Following

With input from locomotive tracking hardware, Virtual Sound Decoder is able to move the apparent source of the locomotive sound to follow the locomotive's position on the layout.

By adding some geometric layout data, the sound will follow the locomotives continuously (without a "jump").

Note: JMRI Test Release 4.13.2 or newer required.

Advanced Location Following Setup

A file named VSDGeoData.xml is required, which provides two general attributes and some specific attributes for each location.

Here is an example of a VSDGeoData.xml with one location (geodataset):

        <?xml version="1.0" encoding="UTF-8"?>
        <vsdecoder-geodata xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
           <layout-scale>160</layout-scale>
           <check-time>2000</check-time>
           <setup>
              <geodataset>
                 <reporter-systemname>LR1</reporter-systemname>
                 <position>(-1.5, 1.1, 0.0)</position>
                 <radius>0.0</radius>
                 <slope>0.0</slope>
                 <length>3.0</length>
                 <end-position>(1.5, 1.1, 0.0)</end-position>
              </geodataset>
           </setup>
        </vsdecoder-geodata>

The route in this example is defined as a straight line parallel to the X axis, with a length of three meters.

The general attributes are:

The attributes for each location are:

Example for curve attributes:

        ...
        <radius>1.18</radius>
        <rotate-xpos>0.0</rotate-xpos>
        <rotate-ypos>0.83</rotate-ypos>
        ...

The location (geodataset) sequence defined in VSDGeoData.xml describes a route on a layout. The described route should go away from the left to the right in forward direction, or in case of a circle, in clock-wise forward direction.

The Advanced Location Following allows up to four locos. Normally only one loco can be detected in a tracking section. If you want to run more than one loco, you may create a JMRI Route (again, up to four for VSD purposes) and add the Route to a Train. Please choose the predetermined Route names VSDRoute1 (default), VSDRoute2, VSDRoute3 or VSDRoute4. On the "Virtual Sound Decoder Manager" window you'll find an "Option" button on each VSDecoder. There you can select a JMRI Train and accordingly a Route. Please note that you need a setup section in your VSDGeoData.xml for each Route you want to use.

How to run a test with the JMRI LocoNet Simulator (without a connection to your layout):

  1. Make sure a Reporter named "LR1" is available after PanelPro has started (follow the directions appropriate to your hardware system for setting up Reporters)
  2. Create a XML file named VSDGeoData.xml (take the example mentioned above) and store the file to the "Users Files Location" (JMRI\<Railroad Name>)
    Note: Please make sure that there are no leading spaces in the first line of the file!
  3. Download the VSD file Class64.vsd from the web
  4. Make sure your computer's audio system is working
  5. Launch PanelPro
  6. Open a JMRI throttle: Tools->Throttle->New Throttle->Address: 3->Set
  7. Add a VSDecoder: Debug->Virtual Sound Decoder->VSDecoder Manager->Add Decoder->Manual->Address: 3->Set->Load VSD File->File name: Class64.vsd->Select a Profile: Class64->OK->Start Engine
  8. Simulate an incoming Reporter: LocoNet->Send LocoNet Packet->Packet: d0 20 00 7d 03 00->Send->close the window
  9. Run the loco and hear the sound wandering from the left to the right

Note: If you choose a Diesel VSD file you might want to add a top-speed element in the config.xml. Please see the config.xml of a Steam VSD file for the syntax and the right place.

During the setting up and test process I recommend to open a JMRI system console, which might provide helpful information: Help > System console.

You might also enrich the logging information, by adding the line

   log4j.category.jmri.jmrit.vsdecoder.VSDGeoFile=DEBUG

to the file default.lcf as the last line. This file is located in your "Settings Location" (JMRI).

Once you have a working setup, you can activate an option in your VSD configuration file to print the calculated position points describing the route of your loco. Please see the "Create XY coordinates output in console for a VSDecoder" option for details.

For questions, please contact me on the JMRI users Groups.io group.

Back