v0.3.0 Beta

This marks another big improvement in usability for ZephyrCab! There are two major feature upgrades with this release:

Automatic Version Detection

ZephyrCab is now aware of its version. It leverages the Git version control system, as well as the releases API on GitHub to determine if you are running the latest version. If there is a newer, stable release, it will alert the user, and provide a link to the release notes. For developers, if you download a copy of ZephyrCab/master, the release version will show as rolling-yourCommitSHA and the updating functionality will be disabled.

Improved Notching Control

This is a small step in improving the UI of ZephyrCab to fit users' needs. I had several people suggest +/- buttons for the throttle, so I've added them just above the 8 position slider. ZephyrCab is still not practical on a smartphone, but it will run great on a tablet, and of course runs great on a desktop or laptop PC as it always has. Smartphones are not off the table; I plan to add better support for small screens in the future!

Usage Data

Let me be clear: I do not intend to invade privacy with this program. This data will not be used for marketing purposes or sold to any third party. The data collected is not personal (an optional username, intended for developers to identify their installations with their GitHub username, is as personal as it gets). The data collection can be turned off entirely by editing /cfg/settings.json. The only reason I am adding this feature is so I can get a better picture of what things I need to support. By gathering JMRI rosters and other non-personal layout data, I can figure out which decoders I need to prioritize sound support for, which models I should release premade bundles for, and extrapolate other users' needs. If you are not comfortable sending in non-personally-identifiable usage data, you may disable all the data collection by setting cfg.disableAnonymousUsageData to true in the /cfg/settings.json file. The source code for the data collection system is available in its entirety at https://github.com/k4kfh/ZephyrCab/blob/master/scripts/stats.js.

Notes:

• This release may still behave a little odd in Firefox. I still recommend using the latest version of Chrome wherever possible.

Make an issue on GitHub or join the Gitter chat if you encounter any further issues. Enjoy!

v0.2.1 Beta

Feature-wise, this is essentially a re-release of v0.2-beta, however this version actually works for a change. All the idiotic known bugs in the previous version have been repaired in this version.

Summary

This is the first "real" release of ZephyrCab. It's not 100% production-ready yet, but it is fairly stable and much more accessible than it has been in the past. You don't have to know the first thing about programming to get started with this!

Features

This release brings some much-needed backend fixes, and some monumental usability improvements!

• An early iteration of wheel slip is added to the simulation, focused primarily on slipping during acceleration
• The UI has been made extremely tablet-friendly, complete with a fullscreen button to make the most of your tablet's display. This release has been tested extensively on a Nexus 7 Tablet, and should work fine on nearly any tablet with a web browser.
• The initial setup process has had some dramatic improvements:
  • There is (basic) support for ALL DCC decoders now! If your DCC decoder's advanced sound features are not supported, ZephyrCab will automatically fall back to basic speed/direction/lighting support, available for every DCC decoder.
  • Adding locomotives has been made exponentially more user-friendly. Where in previous releases, you had to manually edit a couple JSON files (where any misplaced curly brace could break the entire application), this release has some major changes to that system. Each locomotive now has its own separate bundle file, and you can simply drag/drop them into the /cfg/bundles folder. The files are also much easier to create: you don't need to have a deep knowledge of ZephyrCab's physics system, you just need a data sheet on your locomotive. ZephyrCab now includes an easy web GUI for generating bundles files. Simply fill out a form with your locomotive's data, and click the download button to receive your bundles file and follow the instructions.

• Dealing with the scale speed feature is also much simpler in this release. As you can see in the photo above, it is included in the bundle generator GUI. Simply use a scale speedometer and some simple proportion math to get a factor for converting DCC speed steps into scale speed, and input that coefficient into the bundle generator.

These usability improvements should make ZephyrCab more accessible to "normal" people. You no longer have to be a programmer to get started with it!

Feel free to make an issue on GitHub if you run into any problems with this release, or if you have feature requests/suggestions/questions. I hope you guys enjoy this!

Known Issues

• This release still has a few weird behaviors in Firefox. It will usually work fine, but every now and then it gets very confused about the JMRI roster. This seems to only happen in Firefox, and I'm not sure why. If possible, use Chrome, but if you run into problems in Firefox, refreshing the page seems to fix it.

v0.2 Unstable Beta

This release is NOT stable. There is a major bug with importing bundles that was just discovered. I apologize for the inconvenience. At this point, you should download v0.2.1-beta, which is essentially a fixed version of this release.

This release brings some much-needed backend fixes, and some monumental usability improvements!

• An early iteration of wheel slip is added to the simulation, focused primarily on slipping during acceleration
• The UI has been made extremely tablet-friendly, complete with a fullscreen button to make the most of your tablet's display. This release has been tested extensively on a Nexus 7 Tablet, and should work fine on nearly any tablet with a web browser.
• The initial setup process has had some dramatic improvements:
  • There is (basic) support for ALL DCC decoders now! If your DCC decoder's advanced sound features are not supported, ZephyrCab will automatically fall back to basic speed/direction/lighting support, available for every DCC decoder.
  • Adding locomotives has been made exponentially more user-friendly. Where in previous releases, you had to manually edit a couple JSON files (where any misplaced curly brace could break the entire application), this release has some major changes to that system. Each locomotive now has its own separate bundle file, and you can simply drag/drop them into the /cfg/bundles folder. The files are also much easier to create: you don't need to have a deep knowledge of ZephyrCab's physics system, you just need a data sheet on your locomotive. ZephyrCab now includes an easy web GUI for generating bundles files. Simply fill out a form with your locomotive's data, and click the download button to receive your bundles file and follow the instructions.

• Dealing with the scale speed feature is also much simpler in this release. As you can see in the photo above, it is included in the bundle generator GUI. Simply use a scale speedometer and some simple proportion math to get a factor for converting DCC speed steps into scale speed, and input that coefficient into the bundle generator.

These usability improvements should make ZephyrCab more accessible to "normal" people. You no longer have to be a programmer to get started with it!

Feel free to make an issue on GitHub if you run into any problems with this release, or if you have feature requests/suggestions/questions. I hope you guys enjoy this!

Known Issues:

• License: Initially, the zipped releases did not include the appropriate AGPLv3 license (for about the first 48 hours). These releases still (like all ZephyrCab releases) fall under the AGPLv3 license. I have since fixed the issue, and the ZIP file available below includes the full text of the GNU Affero General Public License Version 3.
• JMRI Roster Names with Spaces: If you try to use ZephyrCab with a locomotive that has spaces in its name in the JMRI roster, you will run into issues. ZephyrCab just doesn't handle the spaces in the bundle file name correctly. If you generate a bundle for your locomotive, please change any spaces to underscores (or remove them altogether) in the filename. Also be sure to make the same changes when you add the filename to bundles.list.json. For example, if I generate a bundle for a locomotive named BN #1379, ZephyrCab's bundle generator tool will give me a file called BN #1379.zephyrcab. Change the name to BN_#1379.zephyrcab, and be sure to enter BN_#1379.zephyrcab in the bundles.list.json file. Then all should be well. This is a minor issue and will be fixed in the next release.

First Alpha Release (no wheel slip or dynbrakes)

This is the first "complete" release. It is missing two key things: wheel slip and dynamic brakes. It's also only got one bundle file, the EMD F7-A, but that will be remedied over time. To install, unzip and follow the instructions in the README to extract into your JMRI web server.

The bundles.js file is the first thing you'll want to edit. It "bundles" JMRI roster entries (for control of your model) with the appropriate physics data (for accurate simulation of your model). If your computer doesn't know how to open it, you can edit it in Notepad. On line 25, where it change CBQ2 to the name of the locomotive you wish to test with. An F-unit would be the best to test with as the simulator only has data on F units for the moment, but you can test with anything you like and it will simply handle like an F unit.

    "CBQ2": { //you want to change this line!
        type: "locomotive",
        model: {

For instance, if the locomotive I wanted to use was named BN #1379 in my JMRI roster, I would edit like so (make sure to leave the quotes):

    "BN #1379": { //you want to change this line!
        type: "locomotive",
        model: {

I understand this is a clunky way of handling this and I do plan on improving it in the near future, it just hasn't been a top priority while I get the basic physics stuff worked out.

Once you've finished those edits ZephyrCab will be able to match everything it needs to know about your locomotive. Open the webpage (see README installation instructions if you're not sure how to get there) and you should see a notification that ZephyrCab automatically connected to your JMRI installation.

Using ZephyrCab

• Go over to the "Train Settings" tab. When you start ZephyrCab you'll have to configure your train here so the software knows how many cars you have (or want to simulate) in order to accurately reproduce handling and braking characteristics. Add your locomotive first (it should show with your JMRI roster's name) and then add as many boxcars as you want (these are purely simulated for weight/braking). 5-6 is a good amount to start playing with.

• Once you've done that, move over to the "cab" tab. Flip the switch to start your engine, and bear in mind that unless you have an ESU LokSound EMD 567 decoder, your sound will not function in this release. This is a feature that will definitely be added, I just have to add support for other decoders. If you have a decoder you want support for please let me know so I can expedite development for that specific decoder.

• The engine is running, so now put the reverser in forward by dragging it. Then move the throttle up to notch 1. You should see the ammeter on the dashboard increase, indicating that your locomotive is now under some electrical load (of course this is all fabricated by the physics engine; no DCC system would pull this many amps, so don't panic). If you've added a lot of cars you may have to increase the throttle more to get the train to move, but sooner or later you should see the speedometer slowly start increasing and your locomotive should begin crawling along.

• The rest of the UI is relatively self explanatory. The automatic brake is a simplified version of a self lapping brake valve found in locomotives, and the independent brake is a simplified version of a self lapping independent brake valve (note the "bail off" feature; that removes air from the independent brake after an automatic brake application).

---

I plan on releasing more thorough documentation on how to actually drive with these controls soon, but feel free to ask questions/make suggestions. If you run into any bugs/problems, please let me know ASAP so I can investigate.

Happy railroading!