A new concept in Model Railroad Control.

Getting Started

This online help is intended as a Loco Operator reference and is quite complicated in places. In order to get your model railroad Wi-Fi network up and running with the minimum effort, it is recommended that the Quick Start document be followed. This takes you through the steps of:

  • 1. Getting your locomotive working in Direct Wi-Fi mode.
  • 2. Driving your locomotive and simple tuning.
  • 3. Setting up your infrastructure model railroad network and switching your locomotive(s) over to behave as stations on your infrastructure Wi-Fi network.
  • 4. Operating two locomotives from one instance of Loco Operator.
  • 5. Building your first multiple unit consist.

You can read the Quick Start document at
http://www.wifitrax.com/appNotes/Quick-Start.pdf

You can also read about networking with WifiTrax in the document Managing your Model Railroad Network
http://www.wifitrax.com/appNotes/Managing-your-Model-Railroad-Wi-Fi-Network.pdf

Networks

Central to the WifiTrax system of model railroad control is the concept of networks. We use this term to mean a collection of devices under control of a network router that may be accessed by the computer on which Loco Operator is installed. The devices on a network obtain their IP address from that router.

Network Scan

When you start Loco Operator for the first time, it will ask you to let it scan your device to see the networks that are accessible to it. For a tablet or phone device, these will usually be Wi-Fi networks that the device can connect to. You can repeat the scan at any time by tapping or clicking the "Scan Nets" button.

Figure 1 Network Scan

If you have installed on a desktop machine that has an Ethernet LAN adapter (network interface card) then that will appear as a network. On a typical laptop computer, you will probably have both an Ethernet LAN adapter and a Wi-Fi adapter, so both of these will appear as networks.

Figure 2 Networks Page

Networks are managed on the Settings tab towards the right at the top of the Loco Operator display. The Settings tab has two pages: General and Network. Networks are, of course managed on the Networks page of the Settings tab.

At the top of the Networks page, there is a Drop-down selector called Displayed Network. You can select any network here and the details will be shown in the blue section below. After you have scanned for networks, you will typically see a list including your Wi-Fi Access Point on your router, maybe a LAN network, some inaccessible access points for your neighbors and one or two beginning with "ESP_". These are the access points provided by your WifiTrax locomotive controllers, called Controller Networks. There may also be a Bluetooth network listed, which is not relevant to the App at this time. In the example the relevant networks are:

The Controller networks, beginning with ESP_, are networks provided by WifiTrax locomotives. On these networks, the locomotive is the access point and manages the network, acting as the DHP Server, handing out IP addresses to other computers connecting to it. It is its own Network Router, if you like. As well as managing its own network, the locomotive can also join another network as a station.

Figure 3 Typical Networks List

In the example, the following networks have been found:

  • Bluetooth Network Connection - not relevant.
  • Ethernet - the wired LAN to which this computer is connected.
  • Fon WiFi - an inaccessible neighboring network.
  • ESP_090E31 - a new WifiTrax-installed locomotive.
  • SSSWireless - the infrastructure Wi-Fi network provided by the network router.
  • ESP_090E36 - a new WifiTrax-installed locomotive.

Note that the last six digits of the locomotive Controller Networks are the last six digits of the AP MAC address printed on the label of the bag in which your WifiTrax controller module was shipped.

For each Infrastructure Network, a range of IP addresses can be reserved for WifiTrax controllers to use when acting as stations.

There are six pieces of information displayed when a network is selected.

  • Network Type - Controller AP, Infrastructure AP or Wired LAN.
  • Subnet Address - this must match the subnet of the DHCP controlling the network.
  • First Address in Subnet - the first IP Address dedicated to WifiTrax controllers.
  • Last Address in Subnet - the last IP Address dedicated to WifiTrax controllers.
  • Wireless Router SSID - the SSID of the wireless access point of the network.
  • Wifi Password - the password required for a station to connect to the network access point.

For a Controller AP, the subnet address will always be 192.168.4.0. For an infrastructure AP or Wired LAN, you must check the subnet address against your router, but it will default to the most common: 192.168.0.0.

For a Controller AP, the start and end address will always be 1, since there is only one controller on the network. For an infrastructure AP or Wired LAN, the range defaults to 1 - 255 but you should limit it to a smaller range and assign reserved IP addresses to your WifiTrax controllers. The range entered here is the range that will be scanned for locomotives. The IP addresses actually assigned wil be under control of your Network Router.

For a Controller Network, the Wireless Router SSID is defined by the WifiTrax module and is of the form ESP_XXYYZZ, where XX, YY and ZZ are the last three pairs of digits of the Station MAC (STA MAC) printed on the bag label of the WifiTrax module, e.g ESP_090E31 for a MAC address ending in -09-0E-31. For an infrastructure network, the SSID is that of your Wi-Fi access point. For a wired LAN network, it is not relevant.

The Wifi password is only needed, for an Infrastructure Network, if you want your controllers to act as stations on that infrastructure network. The password will be given to each controller so that it can connect to your protected infrastructure access point.

Network Re-Scan

You can re-scan your networks at any time by clicking or tapping the Scan Nets button existing networks known to the system will not be lost and any new ones will be added.

You can also remove a net from the system by selecting it in the Displayed Network drop-down and clicking the Forget Net button.

General Settings

These are accessed from the General page of the Settings tab. Tap the settings tab first and then the General button.

Home Network

The first setting on the General Settings page is the Home Network. This is the Infrastructure Network that will be given to WifiTrax Locomotive Controllers for them to connect to as stations. All the locomotives that have been given this information will automatically connect to the home network and can then be controlled when that network is selected as the Operating Network - see below.

You must set up the IP Address range, SSID and Password for the network you choose as home using the Networks page as above. Also you must configure your network router to reserve IP Addresses within that range for the locomotive MAC Addresses. You only need to do this if you limit the IP Address range. You can leave it as 0 - 254, but scanning for locomotives will take a long time.

To give the Home Network information to each locomotive, you use the Tuning tab, see the Tuning section in thes pages.

Operating Network

The next setting on the General Settings page is the Operating Network. This is the Network that will be scanned when you use the Locomotives page and on which you can select locomotives for driving.

The operating network can be either an Infrastructure Network, a Wired LAN Network or a Controller Network. For example, if you have a new locomotive that has not yet joined the home network as a station, you can drive it on its own Controller Network by selecting that as the Operating Network. When you do this, you must connect your computer, tablet or phone to that network's access point using the Settings, Wi-Fi pages on the computer, tablet or phone that you are using.

In another example, you may want to use a Windows 10 desktop that has no Wi-Fi adaptor. Here you would choose your Wired LAN network as your operating network.

Once you have all your locomotives acting as stations on your Home Network, for a Wi-Fi accessible computer, tablet or phone, you will want to choose the Home Network as the Operating Network. Then you will be able to drive any single locomotive, drive two at a time and set up consists from that device.

Tap Amount

The tap amount setting on the General Settings page is the number of speed demand units by which the speed of a driven locomotive will be increased or decreased when the region above or below the thumb box on Speed lever is tapped. The speed demand is an integer between 0 and 1000. The increase or decrease is approximate.

This setting also governs the rate at which the speed will automatically increase or decrease when Auto Drive mode is selected. These features are fully described in the Driving tab section.

Speed Units

The speed units may be selected as MPH or KPH on this drop-down selector. This affects the appearance of all speedometers displayed.

Loco Wi-Fi Timeout

This setting determines the timeout in milli secconds that will be applied to all communications with a locomotive. If the locomotive does not respond during this time the communication will be considered to have failed. After two consecutive failures, the locomotive will be displayed as not responding and driving will no longer be possible. The locomotive will automatically stop after a period of time determined by its Contact Loss Stop Time (mS) described in the Tuning< section.

If a locomotive is determined as not responding, Loco Operator keeps trying to re-establish contact and if contact is re-established, driving may proceed as normal. However after a further period of time, the speed control will be set to zero for safety.

Locomotive Management

On the Locomotives tab, you can manage the locomotives that are present on your Operating Network. When you display this tab it will show the locomotives on the operating network that are already known to the Loco Operator app. Of course when you first use the App, there will be none.

This tab also shows the accessability status of the Operating Network. The network will only be shown as accessible if your computer, tablet or phone is connected to the network. So if the network is shown as Not Accessible, you probably need to go to the Wi-Fi settings on your computer and connect to the network access point.

Once the network is accessible, you can cick the Scan button to scan the network for the locomotive controllers that are present.

The scan will take place over the range of IP addresses that you have defined for the network that is selected as the operating net. In the example shown, the range is the full range of the subnet. In this case the scan will take quite a long time. You can reduce this time by limiting the IP range of the network on the Settings tab, Networks page, but you must make sure that the router will assign IP addresses to the locomotives within this range. You can do this by assigning reserved addresses to the locomotive controller MAC addresses in your router.

Once the scan is complete, you will see a list of the locomotives that have been discovered on the operating network. You can repeat the scan at any time. New locomotives will be added and existing ones updated but existing locomotives that are no longer visible (because they are powered down or off the track) will not be removed.

As well as the accessibility of the network, this page also shows the availability of each locomotive on it. Any that have been discovered in the latest scan will be available, but older ones may be unavailable if they are now powered down or removed from the track.

You can update the accessibility display of the operating net and the availability of the displayed locos by clicking or tapping the Update button. If you have removed a locomotive from the track and replaced it since you viewed the Locomotives tab, you should update with this button.

When you select a locomotive in the list by clicking or tapping it, its details are shown in the panel at the bottom of the screen The information shown here is:

  • Installed Product - The installed WifiTrax product in the locomotive such as WMR-10, WMH-20.
  • MAC Address - The station MAC address of the locomotive controller.
  • IP Address - The IP address of the locomotive controller, as assigned by the DHCP server (i.e. the router) on the operating network.
  • Loco Wi-Fi SSID - The SSID of its Controller Network Access Point.

You can remove a locomotive from the record by selecting it in the list and clicking or tapping the remove button. You can always add the locomotive back by powering it up and repeating the scan.

Driving

Select the Driving tab so that you can choose a locomotive to drive. You must select a locomotive on the driving tab if you want to drive it and also if you want to adjust its configuration variables on the tuning tab.

Selecting the Locomotive

Locomotives are chosen for driving on the Drive: drop-down selector. Only locos that are Available are displayed. Multi-Unit Consists are also displayed. If a locomotive is not powered up, it will not be displayed because it is not available. In addition locomotives that are in consists and also coupled cannot be chosen for separate driving. However a locomotive may be included in one or more consists and will still be available for separate driving if it is not coupled in any of its consists.

Control of Locomotive Lights

The currently available products from WifiTrax provide control of the front and rear lights of the locomotive. Each of these may be in three states: Off, On and Auto. Off means the light is always off, On means it is always on and Auto means that the front or rear light will come on if the locomotive is driven in that direction. Tap or click the buttons to move through the three states. The lights can be changed while the locomotive is in motion.

Control of Locomotive Direction

Tapping the Direction button switches between forward and backwards. The direction button is disabled while the locomotive is in motion. For a multiple unit consist, the direction button applies to the entire consist. It will take into account that some locomotives are facing backwards provided those locos have been set with reverse direction on the consist tab.

Locomotive Driving Mode

The Driving Mode button can be set to Switching or Main Line. In Switching mode it is possible to control the locomotive more precisely at low speed and the top speed is limited to about 15 MPH. In Main Line mode, the top speed is as fast as the locomotive can go but there is still a non-linear response at low speeds to allow for smooth take-offs.

Stop Locomotive

The locomotive can be stopped immediately by clicking or tapping the stop button. The stop button can be used any time. There may be a delay of about a second before the command reaches the locomotive due to network delay. The locomotive will also take time to stop due to its physical momentum - i.e. the momentum of its flywheels and body mass.

Speed Control

The speed of the locomotive is controlled by the Speed Lever. There are two modes of use. With Auto Drive turned off, the speed of the locomotive can be changed by sliding the thumb pad up or down. If the thumb pad is moved fully down, the locomotive will stop completely. As explained in the Locomotive Driving Mode section, the maximum speed will be governed by whether the locomotive is set to Switching or Main Line.

Tapping the region above or below the thumb pad will cause the speed to be increased or decreased by an amount determined by the Tap Amount setting in the General page of the Settings tab.

Auto Drive

Auto Drive is a simple feature that allows you to initiate a smooth change of speed of the locomotive. It is turned on or off by clicking or tapping the Auto Drive button. If you turn Auto Drive on, you can tap or click anywhere on the Tap-Up or Tap-Down region on the Speed Lever and, instead of causing an incremental speed increase, the tap will cause a Target Rectangle to appear at the location of the tap. The speed of the locomotive will then gradually increase or decrease towards the target speed. Once the target speed has been reached, the locomotive will stay at that speed. If you tap right at the bottom of the Tap-Down region the locomotive will slow down and stop. The rate at which the locomotive accelerates or decelerates is determined by the Tap Amount setting on the General Page of the Settings tab. The higher the Tap Amount, the greater the acceleration or deceleration.

If you wish to take manual control of the locomotive before the Auto Drive action is complete, simply touch or move the thumb pad on the speed lever. Turning off Auto Drive will also end the Auto Drive action. You may turn Auto Drive on or off while the locomotive is in motion.

Speedometer

The speedometer shows the approximate speed the locomotive is moving in either Miles per Hour (MPH) or Kilometers per Hour. The speed is obtained from the back e.m.f. generated by the motor, passed through a calibration table to give the speed. The accuracy will depend on the characteristics of the locomotive motor and has been set at the factory for a typical high quality motor such as those fitted in most new locomotives. We intend to allow the user to adjust this in a later version of this App as part of the tuning process. You can select MPH or KPH on the General page of the Settings tab.

Telemetry

You can switch between Speedometer display and Telemetry display by clicking or tapping the Telemetry button. When the Telemetry display is visible, it shows the following information which is an indication of how your locomotive is performing:

  • MPH - The speed in Miles per Hour
  • Demand - The requested speed being sent to the locomotive from this App. The demand is like a speed step and is in the range 0 - 1000. So the WifiTrax system provides a granularity of one part in a thousand - more than you would ever need.
  • Target Speed - The target speed that the locomotive firmware calculates from the demand. The units are AD N, which is an integer count ranging from 0 to 4095. For the technical, this is the required output from the 12-bit A/D Converter converting the motor's back e.m.f to a number N.
  • Measured Speed - The actual speed of the locomotive as measured at the A/D e.m.f. coverter. The units are AD N, which is an integer count ranging from 0 to 4095. For the technical, this is the actual output from the 12-bit A/D Converter converting the motor's back e.m.f to a number N.
  • Proportional Range - The speed control algorithm has a feedback term that is proportional to the error between the Target and Measured speed. The amount is different according to one of three speed ranges (1, 2 and 3). This figure shows the range in which the speed control is operating in.
  • Proportional Term - The actual value of the proportional control term generated from the error between the target and measured speed.
  • Derivative Term - The speed control algorithm also uses a derivative term, which depends on the rate of change of the error.
  • Integral Term - The speed control algorithm also uses an integral term. The purpose of this is to gradually include a fixed error correcting amount so that the proportional term will reduce to zero.
  • Duty Cycle - The duty cycle of the pulse width modulated current passing through the motor. When this is 100%, the locomotive can go no faster.
  • Keep Alive - The percentage of full voltage available from the power maintenance capacitors. This will drop if you go over dirty track.
  • Motor Current - The average current passing through the motor, measured in Amperes.
  • Current Limit Events - A number representing the number of times the current has been limited during approximately the last second. Current limiting is a feature available as part of the locomotive tuning.

Dual Driving Mode

When the Driving tab is displayed, you can switch between single and dual mode as needed using the Single/Dual button outlined above. Tap or click once to go to dual mode, then tap or click again to go back to single mode.

When in dual mode, the driving controls are duplicated, including the locomotive selector. You can select a different locomotive for each set of controls and drive them at the same time. There is no restriction on your choice of locomotive except that you cannot choose the same locomotive for both sets of controls.

The selection on either or both sides can be a multiple unit consist, so you can drive two consists at the same time if you wish.

One restriction is imposed for safety: You cannot go back to single mode if you have a locomotive selected for driving in the right-hand set of controls. You must deselect the right hand locomotive first. You can switch from single to dual mode while driving a locomotive with the left-hand set of controls. So you can switch to dual, drive a loco with the right-hand controls for a while, then switch back to single while continuing to drive with the left hand controls all the time.

In Dual Driving Mode, the setting of the Auto Drive button applies to both sets of controls. You can initiate Auto Drive speed changes independently but you cannot tap up or down on one while using Auto Drive on the other.

Tuning

Select the Tuning tab to adjust configuration variables that govern your locomotives's behavior, but first you must go to the Driving tab, make sure it is in single driving mode and select a Locomotive.

Tuning

Screen Layout

Select the Tuning tab to adjust configuration variables that govern your locomotives's behavior, but first you must go to the Driving tab, make sure it is in single driving mode and select a Locomotive. There are two pages Page 1 and Page 2. You can select one of these using the buttons at the top right of the display. The figure above shows Page 1.

Each page has four columns: The name of the Configuration Variable, the present value as returned from the locomotive, a column of Text Boxes in which new values may be entered and a column of buttons. Clicking or tapping one of these buttons sends the new value of only that configuration variable to the locomotive.

At the bottom of the screen there are four buttons which are described below.

This button refreshes the displayed values displayed on the second column, that are currently in the locomotive.

This button saves the values that are in the locomotive to the Flash memory in the locomotive. This means that they will not be lost when the locomotive is powered down.

This restores all of the tuning configuration variables in the locomotive to their default factory set values. Any changes that you have made will be lost.

This saves all of the configuration variables whose values have been changed to the locomotive. You still have to click the make permanent button to make the changes remain after power is cycled.

Page One Configuration Variables

The configuration variables that can be modified on Page One of the tuning tab are:

  • Low Proportional Coefficient - The muliplier for the speed error used for the proportional feedback term in the speed control algorithm within the Low Range.
  • Low Region Limit - The boundary between the Low Proportional Zone and the Mid Proportional Zone in the Speed Control Algorithm. The units are AD N, i.e. Analog to Digital Converter counts.
  • Mid. Proportional Coefficient - The muliplier for the speed error used for the proportional feedback term in the speed control algorithm within the Middle Range.
  • Mid. Region Limit - The boundary between the Mid Proportional Zone and the High Proportional Zone in the Speed Control Algorithm. The units are AD N, i.e. Analog to Digital Converter counts.
  • High Proportional Coefficient - The muliplier for the speed error used for the proportional feedback term in the speed control algorithm within the High Range.
  • Derivative Coefficient - The muliplier for the speed error used for the derivative feedback term in the speed control algorithm within the Middle Range and High Ranges. The derivative term is not applicable in the low range.
  • Integral Coefficient - The muliplier for the speed error used for the integral feedback term in the speed control algorithm over all ranges.li>
  • Minimum Speed - The minimum speed your locomotive can sustain. When you start your locomotive it will always begin at this speed.
  • Current Limit - The motor current in amperes at which limiting will begin. If this is set to zero, current limit will be turned off. In this case the unit, or your locomotive may overheat. Curren will be permitted above this limit for 0.5 seconds to allow large currents that may be needed for the speed control algorithm to start the motor.

Page Two Configuration Variables

The configuration variables that can be modified on Page Two of the tuning tab are:

  • Direction Reversed - 0 or 1 will reverse direction of travel of the locomotive according to the Direction driving control. You can change this if the motor connections happen to be reversed.
  • Lights Reversed - 0 or 1 will reverse direction of front and rear lights of the locomotive according. You can change this if the front and rear lights happen to have been wired to the wrong connections. The LEDs MUST still be wired the correct way around however or they will not come on.
  • Locomotive Name - A name that you may choose for your locomotive.
  • Station SSID - The SSID of the Access Point of the home network. The home network is the network to which the loco will connect as a station. This is populated automatically from the settings information on the Networks page of the Settings tab for the network chosen as the home network. The Home network is chosen on the General page of the Settings tab.
  • Station Password - The password for the Access Point of the home network. This is populated automatically from the settings information on the Networks page of the Settings tab for the network chosen as the home network. The Home network is chosen on the General page of the Settings tab.
  • Contact Loss Stop Time - This is the time, in milliseconds that the locomotive will continue moving after it has lost contact with the computer, tablet or phone running this App.
  • Momentum - This is an arbitrary number that simulates inertia meaning that the locomotive will take time to respond to the Speed lever setting. The default is 20 which gives a smooth operation without adding very much inertia. You can increase or decrease this a little as required.

Multiple Unit Consists

Select the Consists tab to define groups of locomotives to be driven together as Multiple Unit Consists. Any number of such consists may be defined each containing any number of locomotives. A consist is a definition of an instance of multiple unit operation which may not always be active. A consist is only active when all of its units are coupled, in which case the locomotives cannot be driven independently. Thus a locomotive may be included in any number of consists but only one can be active at any given time.

This versatile arrangement lets you define your consists in advance with the tuning adjusted for best performance. Then when you assemble a consist for driving, you simply set all the locomotives in the consist to coupled and you may drive the consist.

Creating and Naming a New Multiple Unit Consist

To create a new multi unit consist, first click the New Consist button (1 in the diagram). The consist will be created and given a default name.
Then replace the default name with the name that you want (2 in the diagram).
Finally click the Save button (3 in the diagram) to save the name change.

Your new consist will appear in the list of consists. If you select it, information about it will be shown in the details section including a list of locomotives included and the settings for each locomotive as a part of the consist.

Adding Locomotives to a New Multiple Unit Consist

Once you have created and named your new consist, you need to add locomotives to it. You do this by first selecting the locomotive that you want by selecting it in the Available Locomotives List (1 in the diagram). Then you click the Add Locomotive button (2 in the diagram). Repeat this process until you have added those that you require in the consist. Don't worry if you add them in the wrong order, you can change the order later.

See the Details each Locomotive within a Consist

When you have added the locomotives, the consist detail will show the list of locomotives on the left. The details of the locomotive are shown to the right of the list for a selected locomotive.

Set the Direction of Locomotives within a Consist

Within the Loco Details section of the consist for a selected locomotive, there are many adjustments. One is the direction shown above. If the loco is to be facing backwards in the consist, tap or click the direction button so that it points to the left. The direction of travel of that locomotive will then be opposite to the direction of the consist. The rear light will also take the place of the front light for the lights in the consist. If the front light of the consist is turned to on, the backward facing locomotive will have its rear light on with equivalent behavior for the rear light of the consist.

Adjusting the Order of Locomotives within a Consist

To adjust the order of the locomotives in a consist, you can select any locomotive, then tap the Move Forward button to move it forward one place.

Removing Locomotives from a Consist

To remove a locomotive from a consist, select the locomotive and click the remove button.

Coupling the Locomotives

As has been explained earlier, consists can be defined but the locomotives may not be assembled into them. They may be assembled as part of another consist or they may be being driven separately. When the locomotive is coupled in a consist in which it is a member, the locomotive may not be driven separately. Only when at least two consecutive locomotives in a consist are coupled can the consist be driven. This may be required when assembling a consist so that a third locomotive and the partially assembled consist can be driven towards each other.

Of course, just because the loco is marked as coupled does not mean it is physically coupled. That's up to you. In fact when you are tuning a consist to match the speeds of the locomotives, you will want to mark them as coupled but have them physically uncoupled so that you can see if the gap remains approximately constant.

To couple a locomotive, select the locomotive and tap the Couple button. It will change to indicate that the couplings are connected.

Tuning the Consist

The Loco Operator App provides comprehensive facilities to match the speeds of locomotives in a consist over their speed range.

To match the speeds of the locomotives in the consist, you can drive a pair of the locos marked as coupled but physically uncoupled and a short distance apart. You can run the consist at several speeds and use the Tap Up and Tap Down buttons to increase or decrease the speed of a loco in the consist by 5 speed units relative to the consist. The orange rectangle in the diagram indicates which speed range the loco is in, so you know which tap up/down buttons to use.