397 lines
18 KiB
Plaintext
397 lines
18 KiB
Plaintext
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
|
|
<title>JMRI: OpenLCB Firmware Downloader</title>
|
|
<meta name="author" content="Bob Jacobsen">
|
|
<meta name="author" content="B. Milhaupt">
|
|
<meta name="keywords" content="JMRI help digitrax downloader">
|
|
<!--#include virtual="/help/en/parts/Style.shtml" -->
|
|
<!-- center class -->
|
|
|
|
<style>
|
|
.ctr {text-align: center;}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<!--#include virtual="/help/en/parts/Header.shtml" -->
|
|
|
|
<div id="mBody">
|
|
<div id="mainContent" class="no-sidebar">
|
|
<h1>OpenLCB "Download Firmware" Tool</h1>
|
|
|
|
<table border="0">
|
|
<tr>
|
|
<td colspan="2">Table of Contents</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1">
|
|
<ul>
|
|
<li>
|
|
<a href="#General">General information</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#Disclaimer">Disclaimer</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#Updating">Updating Device Firmware Contents</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#Problem">What if my device does not work correctly after updating the
|
|
firmware?</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#Verify">Verifying Device Firmware Contents</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#ErrorMessages">Error Messages</a>
|
|
<ul>
|
|
<li>
|
|
<a href="#NoInputFile">"You Must Select An Input File" Pop-up Window</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#FileNotFound">"File Not Found" Pop-up Window</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#InvalidOptionsInFile">"Invalid value for Options key" Pop-up
|
|
Window</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#FileReadError">"Firmware file cannot be read." Status Message</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#ParameterValidationProblem">"Invalid parameter(s) above." Status
|
|
Message</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#nullFirmwareData">Do not have any firmware information to send."
|
|
Status Message</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#ContentNotUnderstood">"Firmware content in the file is not
|
|
understood" Status message</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#WhatItDoes">What this tool does and does not do</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#UpdatableDevices">Some devices which support firmware update via this
|
|
tool</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#Notes">Other Notes</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#ForHelp">If you need additional help</a>
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
<td colspan="1">
|
|
<a href="LoaderFrameOLCB.png"><img src="LoaderFrameOLCB.png" height="137" width="156"
|
|
alt="Example of the Download Firmware Window"></a>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h2 id="General">General information</h2>
|
|
|
|
<p>Some OpenLCB devices allow users to update the firmware (internal program) via the OpenLCB
|
|
connection. The OpenLCB Download Firmware tool provides a mechanism to perform updates via an
|
|
OpenLCB connection.</p>
|
|
|
|
<p>This tool supports firmware update files distributed in ".hex" file format (sometimes
|
|
referred to as the <a href="https://en.wikipedia.org/wiki/Intel_HEX">Intel "I8HEX" file
|
|
format</a>).</p>
|
|
|
|
<p>The tool automatically determines how to interpret the firmware update and performs a
|
|
number of file and data integrity checks before the update information can be used. If any
|
|
issues are identified in the firmware file, the user is informed and the tool will not allow
|
|
the user to update the device with what could be erroneous firmware information.</p>
|
|
|
|
<h2 id="Disclaimer">Disclaimer</h2>
|
|
|
|
<p><strong>This tool is capable of modifying the firmware in OpenLCB devices in ways that
|
|
could make the devices inoperable.</strong> The developers of this tool have attempted to
|
|
reduce the chances that the tool would corrupt a OpenLCB device's firmware. <strong>We cannot
|
|
guarantee that there is no risk of corrupting device firmware when using this tool.</strong>
|
|
It is impossible for the tool developers to predict every way of using the tool and it is
|
|
impossible to predict the nuances of various devices, firmware files, computer operating
|
|
systems, computer-to-OpenLCB interface hardware, etc.</p>
|
|
|
|
<p>In cases where a firmware update attempt does not apply properly, it is often possible to
|
|
<a href="#Problem">re-apply the firmware update to the device</a> to restore proper device
|
|
functionality. This has been recommended by at least one OpenLCB device manufacturer and has
|
|
been found to be effective in some cases by the developers of this tool.</p>
|
|
|
|
<p><em><strong>Use this tool at your own risk.</strong></em>
|
|
</p>
|
|
|
|
<h2 id="Updating">Updating Device Firmware Contents</h2>
|
|
To use this tool to update a OpenLCB device's firmware:
|
|
<ul>
|
|
<li>Consult the device manufacturer to determine if the device supports user updates of
|
|
firmware.</li>
|
|
|
|
<li>Acquire the appropriate firmware file from the device manufacturer.</li>
|
|
|
|
<li>The device being updated must be plugged into a live OpenLCB connection. If the device
|
|
can be battery powered, ensure that the batteries are good before starting this process. If
|
|
the device uses an external power supply, ensure that it is powered and attached.</li>
|
|
|
|
<li>Some devices may require changes to jumpers or DIP switch settings, and perhaps require
|
|
removal and restoration of power, in order to allow the device to accept the firmware
|
|
update via OpenLCB. Consult the node's manufacturer's firmware update instructions for
|
|
details.</li>
|
|
|
|
<li>Open the OpenLCB Firmware Download tool by selecting the "Download Firmware" item from
|
|
the OpenLCB menu. If you have more than one OpenLCB connection, you must open the tool from
|
|
the OpenLCB menu which is associated with the connection which communicates with the device
|
|
you wish to update.</li>
|
|
|
|
<li>Click the Select button, and select the .hex file you want to use as the source of your
|
|
firmware update. Click the Open button to select the file for use. The file will then be
|
|
read and inspected for errors.
|
|
<p>If the file is read and parsed successfully, the tool window will enable the
|
|
"Download" button, and update the status message at the bottom of the window to state
|
|
"Click Download to download new firmware".</p>
|
|
|
|
<p>If the file cannot be read and parsed successfully, a pop-up message will appear or
|
|
the tool window will update the status message at the bottom of the window with a
|
|
description of the problem it found. For more information, see <a href=
|
|
"#ErrorMessages">Error Messages</a>, below.</p>
|
|
</li>
|
|
|
|
<li>Click the Download button to update the firmware in the device. This may take a few
|
|
seconds or minutes, depending on the amount of firmware to be updated and the speed at
|
|
which the messages are sent to the device. A progress bar is displayed below the
|
|
"Download", "Verify", and "Abort" buttons to show progress of the update process. The bar
|
|
will darken from one end to the other as the update gets closer to completion.</li>
|
|
|
|
<li>Once the update tool completes its work, <em>the tool is unable to tell if the OpenLCB
|
|
device has properly written the update</em>. The OpenLCB messaging used for the firmware
|
|
update and firmware verify processes does tell JMRI that the node accepted the data and
|
|
says it did write it OK, but JMRI can't actually test to see if that's true. Because of
|
|
this limitation, the tool is only able to report that it has completed its work. It's
|
|
possible that the node didn't to the programming properly.
|
|
<p>The device may provide an indication that the update process has completed (or failed)
|
|
using lights on the product or on the display of the product. Consult the device
|
|
manufacturer's instructions for further information.</p>
|
|
</li>
|
|
|
|
<li>After performing the firmware update, it may be necessary to reset or remove and
|
|
restore power to the device. Consult the manufacturer's firmware update instructions.</li>
|
|
</ul>
|
|
|
|
<h2 id="Problem">What if my device does not work correctly after updating the firmware?</h2>
|
|
|
|
<p>Sometimes the device firmware update process does not appear to work, and the device may
|
|
fail to provide its normal functionality. <em>Often, repeating the firmware update process
|
|
one or more times will solve the problem.</em> This has been recommended by at least one
|
|
OpenLCB device manufacturer and has been found to be effective in many cases by the
|
|
developers of this tool.</p>
|
|
|
|
<p>In other cases, a device may not be easily restored to proper operation after a firmware
|
|
update attempt. In this case, consult the device manufacturer for further instructions.</p>
|
|
|
|
<p>Consult your device documentation and, if necessary, the device manufacturer's technical
|
|
support if your device fails to function properly after updating its firmware.</p>
|
|
|
|
<h2 id="ErrorMessages">Error Messages</h2>
|
|
|
|
<p>This tool can identify problems at two different stages of the firmware update process.
|
|
The tool checks for problems within the firmware update file when reading the file. When the
|
|
user activates the "Download" button, the tool checks the validity of the parameters which
|
|
the user can change in the tool window for obvious problems. (Many download files don't have
|
|
parameters, so this might not apply to you) If any issues are found at either of these
|
|
stages, the tool will update the message at the bottom of the tool window. If a parameter is
|
|
found to be out of range, that parameter value will be shown with red text instead of black
|
|
text. The "Download" and "Verify" buttons will not perform any useful function if any of the
|
|
parameters are invalid.</p>
|
|
|
|
<p>Typically, when this type of pop-up window appears, a message in the JMRI "console" log
|
|
will provide additional technical detail about the problem. The firmware update file provider
|
|
may find this information useful in correcting firmware update file issues.</p>
|
|
|
|
<p>The tool may also create a pop-up window under certain circumstances.</p>
|
|
|
|
<h3 id="NoInputFile">"You Must Select An Input File" Pop-up Window</h3>
|
|
|
|
<p>The tool will open a pop-up window with this message if the user uses the "Cancel" button
|
|
on the file selection pop-up window. The tool cannot perform a firmware update if no firmware
|
|
file is selected.</p>
|
|
|
|
<h3 id="FileNotFound">"File Not Found" Pop-up Window</h3>
|
|
|
|
<p>The tool will open a pop-up window if the file selected by the user does not exist. The
|
|
pop-up window will state that the file was not found. Use the "Select" button to re-specify
|
|
the correct firmware file.</p>
|
|
|
|
<h3 id="InvalidOptionsInFile">"Invalid value for Options key" Pop-up Window</h3>
|
|
|
|
<p>The tool will open a pop-up window if the file selected by the user contains a value for
|
|
the "Options" key which is not supported by this tool. Consult the device manufacturer for
|
|
advice if this occurs.</p>
|
|
|
|
<h3 id="FileReadError">"Firmware file cannot be read." Status Message</h3>
|
|
|
|
<p>This status message is shown when an abnormal event occurs which prevents the tool from
|
|
reading the file from the disk. This is typically a problem with the computer or the media
|
|
from which the file is being read.</p>
|
|
|
|
<h3 id="ParameterValidationProblem">"Invalid parameter(s) above." Status Message</h3>
|
|
|
|
<p>This message indicates that one or more of the values are out of range. Usually it is
|
|
unnecessary for the user to change any of the parameter values because either the tool's
|
|
default values are appropriate or because the firmware file specifies the required values. If
|
|
an invalid value is found in one of the parameter entry fields, the invalid parameter will be
|
|
highlighted in red. To resolve the problem, close the Firmware Download tool, then re-open it
|
|
and re-read the file. Be careful not to change any of the parameter field values. If the tool
|
|
still identifies a value as invalid, consult the device manufacturer.</p>
|
|
|
|
<h3 id="nullFirmwareData">"Do not have any firmware information to send." Status Message</h3>
|
|
|
|
<p>This status message indicates that the firmware file did not contain any valid firmware
|
|
information. Consult the device manufacturer for a valid firmware file.</p>
|
|
|
|
<h3 id="ContentNotUnderstood">"Firmware content in the file is not understood" Status
|
|
message</h3>
|
|
|
|
<p>When the tool reads a firmware file which it does not understand, it will show the message
|
|
"Firmware content in the file is not understood by this reader." in the status line at the
|
|
bottom of the tool window. Consult the device manufacturer for support - usually this means
|
|
that the manufacturer must provide a new firmware file.</p>
|
|
|
|
<h2 id="WhatItDoes">What this tool does and does not do</h2>
|
|
|
|
<p>The table below shows some capabilities and limitations of this tool.</p>
|
|
|
|
<table border="2">
|
|
<tr>
|
|
<td class="ctr"><strong>"Download Firmware" Tool Capabilities</strong>
|
|
</td>
|
|
<td class="ctr"><strong>"Download Firmware" Tool Limitations</strong>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>This tool can read a firmware update file from the computer's local storage.</td>
|
|
<td>This tool does not acquire firmware update files from manufacturers.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>This tool can send the contents of a firmware update file to the node with a request
|
|
that the associated device update its firmware based on the contents of the
|
|
transfer.</td>
|
|
<td>This tool cannot know whether any of the firmware update file information was
|
|
successfully programmed into a OpenLCB device's memory.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
</td>
|
|
<td>This tool cannot know whether any of the firmware update file information actually
|
|
matches or is different from information within the device's firmware.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
</td>
|
|
<td>This tool does not read the contents of a OpenLCB node's firmware.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h2 id="UpdatableDevices">Some devices which support firmware update via this tool</h2>
|
|
|
|
<p>The table below lists some devices which are believed to allow firmware updates using this
|
|
tool. This list is not necessarily complete, and does not necessarily apply to all versions
|
|
of the listed devices.</p>
|
|
|
|
<table border="2">
|
|
<thead>
|
|
<tr>
|
|
<td class="ctr"><strong>Manufacturer</strong>
|
|
</td>
|
|
<td class="ctr"><strong>Product</strong>
|
|
</td>
|
|
</tr>
|
|
</thead>
|
|
|
|
<tr>
|
|
<td rowspan="2" class="ctr">???</td>
|
|
<td>???</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>???</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td rowspan="1" class="ctr"><!--RR-CirKits-->
|
|
</td>
|
|
<td>???</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="2" class="ctr"><strong>Table updated June, 2015</strong>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h2 id="Notes">Other Notes</h2>
|
|
|
|
<ul>
|
|
<li>The tool automatically determines whether the file uses 16-bit or 24-bit addressing.
|
|
The user can't change that selection. This removes the possibility that the wrong setting
|
|
could be used.</li>
|
|
|
|
<li>It's OK to have multiple OpenLCB Firmware Download windows open at the same time. You
|
|
can perform firmware updates and/or verifies to separate nodes simultaneously, although
|
|
this will be slower than doing them one at a time.</li>
|
|
|
|
<li>If the selected update file's filename is too long to fit the tool window, the filename
|
|
will be displayed in a shortened form. If the cursor is placed over the displayed filename,
|
|
the "tool tip" will attempt to show the complete file name.</li>
|
|
</ul>
|
|
|
|
<h2 id="ForHelp">If you need additional help</h2>
|
|
|
|
<p><strong>If you experience difficulty with this tool and believe that your problem is
|
|
caused by the tool, seek help through the JMRI Users at Groups.io.</strong>
|
|
</p>
|
|
|
|
<p>If you believe that your problem is related to the firmware update file or the hardware
|
|
itself, consult the hardware instructions and the hardware manufacturer's technical
|
|
support.</p>
|
|
|
|
<h2 id="FUNMRA">OpenLCB Technical Note</h2>
|
|
This tool relies for reliable operation on an OpenLCB feature called "Freeze/Unfreeze". For
|
|
more information on that, including issues of standards compliance, please see the <a href=
|
|
"https://jmri.org/JavaDoc/doc/jmri/jmrix/openlcb/swing/downloader/package-summary.html">package
|
|
documentation</a>.
|
|
<p>(This is the package/jmri/jmrix/openlcb/swing/downloader/LoaderFrame help page)</p>
|
|
<!--#include virtual="/help/en/parts/Footer.shtml" -->
|
|
</div>
|
|
</div>
|
|
<!-- close #mBody -->
|
|
<script src="/js/help.js"></script>
|
|
</body>
|
|
</html>
|