OpenLCB "Download Firmware" Tool
General information
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.
This tool supports firmware update files distributed in ".hex" file format (sometimes referred to as the Intel "I8HEX" file format).
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.
Disclaimer
This tool is capable of modifying the firmware in OpenLCB devices in ways that could make the devices inoperable. The developers of this tool have attempted to reduce the chances that the tool would corrupt a OpenLCB device's firmware. We cannot guarantee that there is no risk of corrupting device firmware when using this tool. 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.
In cases where a firmware update attempt does not apply properly, it is often possible to re-apply the firmware update to the device 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.
Use this tool at your own risk.
Updating Device Firmware Contents
To use this tool to update a OpenLCB device's firmware:- Consult the device manufacturer to determine if the device supports user updates of firmware.
- Acquire the appropriate firmware file from the device manufacturer.
- 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.
- 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.
- 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.
- 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.
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".
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 Error Messages, below.
- 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.
- Once the update tool completes its work, the tool
is unable to tell if the OpenLCB device has properly
written the update. 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.
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.
- 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.
What if my device does not work correctly after updating the firmware?
Sometimes the device firmware update process does not appear to work, and the device may fail to provide its normal functionality. Often, repeating the firmware update process one or more times will solve the problem. 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.
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.
Consult your device documentation and, if necessary, the device manufacturer's technical support if your device fails to function properly after updating its firmware.
Error Messages
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.
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.
The tool may also create a pop-up window under certain circumstances.
"You Must Select An Input File" Pop-up Window
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.
"File Not Found" Pop-up Window
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.
"Invalid value for Options key" Pop-up Window
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.
"Firmware file cannot be read." Status Message
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.
"Invalid parameter(s) above." Status Message
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.
"Do not have any firmware information to send." Status Message
This status message indicates that the firmware file did not contain any valid firmware information. Consult the device manufacturer for a valid firmware file.
"Firmware content in the file is not understood" Status message
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.
What this tool does and does not do
The table below shows some capabilities and limitations of this tool.
| "Download Firmware" Tool Capabilities | "Download Firmware" Tool Limitations |
| This tool can read a firmware update file from the computer's local storage. | This tool does not acquire firmware update files from manufacturers. |
| 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. | This tool cannot know whether any of the firmware update file information was successfully programmed into a OpenLCB device's memory. |
| This tool cannot know whether any of the firmware update file information actually matches or is different from information within the device's firmware. | |
| This tool does not read the contents of a OpenLCB node's firmware. |
Some devices which support firmware update via this tool
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.
| Manufacturer | Product |
| ??? | ??? |
| ??? | |
| ??? | |
| Table updated June, 2015 | |
Other Notes
- 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.
- 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.
- 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.
If you need additional help
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.
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.
OpenLCB Technical Note
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 package documentation.(This is the package/jmri/jmrix/openlcb/swing/downloader/LoaderFrame help page)
