Serge NOEL
415 lines
19 KiB
Plaintext
415 lines
19 KiB
Plaintext
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
|
|
<title>DecoderPro® Main Window</title><!--#include virtual="/help/en/parts/Style.shtml" -->
|
|
<!-- DecoderPro Styles -->
|
|
|
|
<style>
|
|
.dp-center {text-align: center;}
|
|
.dp-right {text-align: right;}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<!--#include virtual="/help/en/parts/Header.shtml" -->
|
|
|
|
<div id="mBody">
|
|
<!--#include virtual="Sidebar.shtml" -->
|
|
|
|
<div id="mainContent">
|
|
<h1>DecoderPro® Debug Menu</h1>
|
|
|
|
<h2>Virtual Sound Decoder</h2>
|
|
|
|
<div class="dp-right">
|
|
<p><a href="Main_Debug.shtml#vsdecoder">Back</a>
|
|
</p>
|
|
</div>
|
|
|
|
<hr>
|
|
|
|
<h4>Manage VSD Locations</h4>
|
|
|
|
<p><span id="product-desc">The <strong>Manage VSD Locations</strong> window provides a
|
|
consolidated location to manage and set the apparent physical location of sounds for trains
|
|
using Virtual Sound Decoder</span>.</p>
|
|
The <strong>Manage VSD Locations</strong> 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.
|
|
<h5>Reporters</h5>
|
|
<img src="images/VSD_Locations01.png" alt="Manage Reporter Locations" width="550" height=
|
|
"356">
|
|
<p>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.</p>
|
|
|
|
<h5>Blocks</h5>
|
|
<img src="images/VSD_Locations02.png" alt="Manage Block Locations" width="550" height="232">
|
|
<p>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. Using occupancy
|
|
sensors it's possible to track exactly one loco.</p>
|
|
|
|
<h5>Operations Locations</h5>
|
|
<img src="images/VSD_Locations03.png" alt="Manage Operations Locations" width="550" height=
|
|
"232">
|
|
<p>The Operations Locations tab shows a list of all Locations defined within the JMRI
|
|
Operations system.</p>
|
|
|
|
<h5>Listeners</h5>
|
|
<img src="images/VSD_Locations04.png" alt="Manage Listener Location" width="550" height=
|
|
"232">
|
|
<p>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.</p>
|
|
|
|
<h4 id="VSDLocations">Location Following</h4>
|
|
|
|
<p>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.</p>
|
|
|
|
<h5>Location Following Setup</h5>
|
|
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:
|
|
<ul>
|
|
<li>Digitrax Transponding (tested)</li>
|
|
|
|
<li>Occupancy Sensors and JMRI Blocks (tested)</li>
|
|
|
|
<li>ESU ECoS (not tested)</li>
|
|
|
|
<li>RFID (not tested)</li>
|
|
|
|
<li>RPS (not tested)</li>
|
|
|
|
<li>RailCom / DCC4PC (not tested)</li>
|
|
</ul>
|
|
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 <a href="https://groups.io/g/jmriusers">JMRI
|
|
users Groups.io group</a>. More systems will be added in the future. To enable VSD Location
|
|
Following, follow these steps:
|
|
<ol>
|
|
<li>Follow the directions appropriate to your hardware system for setting up
|
|
<!-- link below should point to the HELP page for Reporters -->
|
|
<!-- klk32003: it is the HELP page (part 2) for Reporters -->
|
|
<a href="../../html/tools/Reporters.shtml">Reporters</a> or <a href=
|
|
"../../html/tools/Sensors.shtml">Sensors</a>.
|
|
</li>
|
|
|
|
<li>Select Tools->Virtual Sound Decoder->Manage VSD Locations</li>
|
|
|
|
<li>In the dialog, set X / Y / Z coordinates for each Reporter (or other Objects) you wish
|
|
to use for VSD location following. Uncheck the "Use Location" box for Objects you do not
|
|
wish to use for VSD tracking.</li>
|
|
|
|
<li>Click "Save" to store the new values.</li>
|
|
|
|
<li>Save your configuration either in a config file or as part of a Panel</li>
|
|
</ol>
|
|
|
|
<p><em>Note:</em> Reporters and Blocks are not added to the Manage VSD Locations "live". If
|
|
you add new Reporters or Blocks, you must close and re-open the Manage VSD Locations window
|
|
to make the new Reporters or Blocks appear.</p>
|
|
|
|
<h5>Coordinate System</h5>
|
|
|
|
<p>The VSD Locations system uses a standard "right handed" <a href=
|
|
"http://en.wikipedia.org/wiki/Cartesian_coordinate_system">Cartesian coordinate system</a>,
|
|
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.</p>
|
|
|
|
<p>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".</p>
|
|
|
|
<p><em>Note:</em> 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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<h5>Listener Location</h5>
|
|
|
|
<p>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 or other Objects.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<h5>Using Locations</h5>
|
|
|
|
<p>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.</p>
|
|
|
|
<p><em>Note:</em> 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 or blocks.</p>
|
|
|
|
<h5>Location Following using Occupancy Sensors and JMRI Blocks</h5>
|
|
|
|
<p>If you have installed occupancy sensors, you can use JMRI Blocks to enable a location
|
|
following.</p>
|
|
|
|
<p>A convenient way to do the setup is creating a Panel with the JMRI Layout Editor. A Layout
|
|
Editor guidance can be found <a href=
|
|
"../../package/jmri/jmrit/display/LayoutEditor.shtml">here</a>.</p>
|
|
|
|
<p>Your Panel should have all the Blocks and attached Sensors you need. Test and store the
|
|
Panel.<br>
|
|
Then launch the VSDecoder Manager window and create a VSDecoder.<br>
|
|
To start the location following enter the number of the VSDecoder locomotive address into the
|
|
Value field of your starting block (Tools->Tables->Block). This sets the new sound
|
|
position. Now run your locomotive.</p>
|
|
|
|
<h5>Location Following using JMRI Operations</h5>
|
|
|
|
<p>If you do not have a hardware tracking system, you can use the JMRI Operations feature to
|
|
enable a rudimentary form of location following.</p>
|
|
|
|
<p>To set the Operations locations:</p>
|
|
|
|
<ol>
|
|
<li>Select Tools->Operations->Locations</li>
|
|
|
|
<li>Create Operations Locations within JMRI Operations</li>
|
|
|
|
<li>Launch the Manage VSD Locations window</li>
|
|
|
|
<li>Set the locations of the defined Operations Locations.</li>
|
|
</ol>
|
|
|
|
<p>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 <em>MOVE</em>
|
|
the train in Operations, the sound will move to the next location on the Route.</p>
|
|
|
|
<p>For more information on Operations, see the JMRI® Operations User's Guide</p>
|
|
|
|
<h4 id="advanced_location_following">Advanced Location Following</h4>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>The next section presents two setup possibilities - a newer and simple way based on a
|
|
LayoutEditor panel and an earlier way by adding some geometric layout data into a file.
|
|
</p>
|
|
|
|
<h5>Advanced Location Following Setup</h5>
|
|
|
|
<p>Since JMRI 4.99.5 there is an easy way to use Advanced Location Following.
|
|
For the setup a LayoutEditor (LE) panel and a simple VSDGeoData.xm file is required.</p>
|
|
|
|
<p>The LE Panel must meet some minimum standards:</p>
|
|
|
|
<ul>
|
|
<li>at least one Track Segment with a Block</li>
|
|
<li>no errors with Tools->Check (e.g. Un-Blocked Tracks)</li>
|
|
<li>the LE panel should be close to the physical layout scale (if you want to use VSD
|
|
on a real layout - this is not important for VSD in Simulator Mode)</li>
|
|
</ul>
|
|
|
|
<p>Here is an example of a VSDGeoData.xml:</p>
|
|
<pre>
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<vsdecoder-geodata xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
|
|
<layout-scale>N</layout-scale>
|
|
<check-time>2000</check-time>
|
|
<models>Layout Editor Clinic - Full Signals</models>
|
|
<models-origin>(346, 260, 0)</models-origin>
|
|
</vsdecoder-geodata>
|
|
</pre>
|
|
|
|
<p>The attributes are:</p>
|
|
|
|
<ul>
|
|
<li>layout-scale: scale of the layout, default: N</li>
|
|
<li>check-time: interval for calculating a new locomotive position; minimum: 500,
|
|
maximum: 5000; default: 2000 milliseconds.</li>
|
|
<li>models: the title of the LE panel</li>
|
|
<li>models-origin: a location in the LE panel to mark the listener position; 3rd
|
|
value is always zero; default: (346, 260, 0)</li>
|
|
</ul>
|
|
|
|
<p>The file VSDGeoData.xml should be located in the same folder as your LayoutEditor
|
|
panel.</p>
|
|
|
|
<p>To run a locomotive open PanelPro and load your LayoutEditor panel first. Then add a
|
|
VSDecoder and start the engine. Now enter the DCC address in the Block Tables into a
|
|
possible starting Block, then open the throttle.</p>
|
|
|
|
<p>The current sound position is printed in the System Console.</p>
|
|
<p>No further block setting is necessary if your are in Simulator Mode and the CheckBox
|
|
"Use Blocks" in VSD Preferences is unchecked.</p>
|
|
<p>Watch the System Console for events that stop the sound positioning.</p>
|
|
<p>To use another panel do also change the panel title in the VSDGeoData.xml.</p>
|
|
|
|
<p>Turntables are not supported. The sound position remains unchanged, until you
|
|
reverse the locomotive traveling direction.</p>
|
|
|
|
<p>Routes, Signals and Dispatcher are not tested.</p>
|
|
<p><em>Note:</em> To hear the surround sound, at least two speakers are required.</p>
|
|
|
|
|
|
<p><strong>And here is the old setup version of Advanced Location Following.</strong></p>
|
|
|
|
<p><em>Note:</em> JMRI Test Release 4.13.2 or newer required.</p>
|
|
|
|
<p>A file named VSDGeoData.xml is required, which provides two general attributes and
|
|
some specific attributes for each location.</p>
|
|
|
|
<p>Here is an example of a VSDGeoData.xml with one location (geodataset):</p>
|
|
|
|
<pre>
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<vsdecoder-geodata xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
|
|
<layout-scale>N</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>
|
|
</pre>
|
|
<p>The route in this example is defined as a straight line parallel to the X axis, with a
|
|
length of three meters.</p>
|
|
|
|
<p>The general attributes are:</p>
|
|
|
|
<ul>
|
|
<li>layout scale (default: N)</li>
|
|
|
|
<li>check time (interval for calculating a new locomotive position; minimum: 500,
|
|
maximum: 5000, default: 2000 milliseconds).</li>
|
|
</ul>
|
|
|
|
<p>The attributes for each location are:</p>
|
|
|
|
<ul>
|
|
<li>system name of the Reporter</li>
|
|
|
|
<li>position (starting point) of the location</li>
|
|
|
|
<li>length of the location in meters</li>
|
|
|
|
<li>type of the location (only two types are supported: line or curve)<br>
|
|
if the location is from type line, a slope value must be provided and the radius must be
|
|
0.0<br>
|
|
if the location is from type curve, a radius value and the circle center point (rotate-xpos
|
|
value, rotate-ypos value) must be provided</li>
|
|
|
|
<li>end-position (endpoint) of the location (last location only)<br>
|
|
if the locomotive is running in a circle, the starting point of the first location and the
|
|
endpoint must be identical</li>
|
|
</ul>
|
|
|
|
<p>Example for curve attributes:</p>
|
|
|
|
<pre>
|
|
...
|
|
<radius>1.18</radius>
|
|
<rotate-xpos>0.0</rotate-xpos>
|
|
<rotate-ypos>0.83</rotate-ypos>
|
|
...
|
|
</pre>
|
|
<p>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.</p>
|
|
|
|
<p>The Advanced Location Following allows up to four locomotives. Normally only one
|
|
locomotive can be detected in a tracking section. If you want to run more than one
|
|
locomotive, 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.</p>
|
|
|
|
<p>How to run a test with the <strong>JMRI LocoNet Simulator</strong> (without a connection
|
|
to your layout):</p>
|
|
|
|
<ol>
|
|
<li>Make sure a Reporter named "LR1" is available after PanelPro has started (follow the
|
|
directions appropriate to your hardware system for <a href=
|
|
"../../html/tools/Reporters.shtml">setting up Reporters</a>)
|
|
</li>
|
|
|
|
<li>Create a XML file named VSDGeoData.xml (take the example mentioned above) and store the
|
|
file to the "Users Files Location" (JMRI\<Railroad Name>)<br>
|
|
<strong><em>Note:</em> Please make sure that there are no leading spaces in the first line
|
|
of the file!</strong></li>
|
|
|
|
<li>Download the VSD file Class64.vsd from <a href="https://github.com/JMRI/vsdecoder">the
|
|
web</a>
|
|
</li>
|
|
|
|
<li>Make sure your computer's audio system is working</li>
|
|
|
|
<li>Launch PanelPro</li>
|
|
|
|
<li>Open a JMRI throttle: Tools->Throttle->New Throttle->Address: 3->Set</li>
|
|
|
|
<li>Add a VSDecoder: Tools->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</li>
|
|
|
|
<li>Simulate an incoming Reporter: LocoNet->Send LocoNet Packet->Packet: d0 20 00 7d
|
|
03 00->Send->close the window</li>
|
|
|
|
<li>Run the locomotive and hear the sound wandering from the left to the right</li>
|
|
</ol>
|
|
|
|
<p><em>Note:</em> If you choose a Diesel VSD file you might want to add a
|
|
<strong>top-speed</strong> element in the config.xml. Please see the config.xml of a Steam
|
|
VSD file for the syntax and the right place.</p>
|
|
|
|
<p>During the setting up and test process I recommend to open a JMRI system console, which
|
|
might provide helpful information: Help > System Console.</p>
|
|
|
|
<p>You might also enrich the logging information, by adding the line</p>
|
|
|
|
<p>You might also enrich the logging information ( see <a
|
|
href="../../apps/Debug.shtml">Debugging and System Logging</a> ), by adding the Logger Category Name
|
|
<br><code>jmri.jmrit.vsdecoder.VSDGeoFile</code> at DEBUG level.</p>
|
|
|
|
<p>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 locomotive. Please see
|
|
the "Create XY coordinates output in console for a VSDecoder" option <a href=
|
|
"VSD_File_and_Config.shtml#xy">for details</a>.</p>
|
|
|
|
<p>For questions, please contact me on the <a href="https://groups.io/g/jmriusers">JMRI users
|
|
Groups.io group</a>.</p>
|
|
|
|
<div class="dp-right">
|
|
<p><a href="Main_Debug.shtml#vsdecoder">Back</a>
|
|
</p>
|
|
</div>
|
|
<!--#include virtual="/help/en/parts/Footer.shtml" -->
|
|
</div>
|
|
<!-- closes #mainContent-->
|
|
</div>
|
|
<!-- closes #mBody-->
|
|
<script src="/js/help.js"></script>
|
|
</body>
|
|
</html>
|