wiFred: WiFi throttle for model railroads using the wiThrottle protocol

More information can be found at https://newHeiko.github.io/wiFred.

Controls and features of the wiFred throttle shows the controls of the wireless throttle. They consist of the following:

As soon as any of the loco selection switches is moved into the "enabled" position, the throttle will boot up and try to connect to a wireless network. When all four loco selection switches are "disabled", the throttle will disconnect from the wireless network after a grace period of five seconds. The device will then go into low power mode, in which the battery will last for more than a year.

If no connection to the network configured into the device can be established within 60 seconds, the throttle will create it’s own wireless network named wiFred-config plus six hex digits taken from the MAC address of the throttle WiFi interface, for example wiFred-config61FB7B, to enable configuration as described in Configuring the wiFred.

Four different locos with long DCC addresses can be assigned to the four loco selection switches. Commands derived from the speed potentiometer, the direction switch and the function keys will be transmitted to all selected locos (near) simultaneously, with a certain translation table enabling some locos to go backwards when others go forwards and also limiting function keys to some of the four locos only - this is described in more detail in Loco configuration and DCC function configuration.

Pushing the red emergency stop key will cause the throttle to send an emergency stop signal to all four locos attached. After an emergency stop, turn the speed potentiometer to zero to re-enable control of the locos.

Pushing the red emergency stop key while holding down the shift key will place the device into configuration mode (as well as issueing an emergency stop to all attached locos). See Configuring the wiFred for more details on how to access the throttle to do the configuration.

Any change in the loco selection switches will cause the throttle to send an emergency stop command to all attached locos. This makes sure that any loco that is deselected will stop on the layout and avoids newly selected locos suddenly taking off at speed. The same is true for a change in the direction switch, to avoid high-speed reverse maneuvers. Turn the speed potentiometer to zero to re-enable control of the locos.

When the battery is low, the device will not re-activate before charging the batteries, but continue operating for approximately an hour if active. When the battery is empty, it will disconnect and enter low power mode. Expected runtime is around 20 hours of full time operations, more if the throttle is placed in low power mode when the locos are not running.

During startup and operation, the LEDs will show the patterns explained in LED patterns and their meaning on the wiFred. After turning off the wiFred, the LEDs will show the current battery voltage for a few seconds, as described in LED patterns and how they show battery voltage when turning off the wiFred.

The wiFred can be charged through the Micro-USB connector at the lower end of the device. Maximum charging current is approximately 400 mA and the device does not communicate with the USB host, so technically there is no guarantee that charging from a USB cable will work, but most chargers, computer ports or power banks do not check the current before powering up.

As long as the battery is being charged, the red charging indicator LED will be lit. When the battery is fully charged, the green charged indicator LED will be lit as long as the charger is still connected. Expected charging time is around five to six hours for a full charge.

Even while charging, the device can still be operated (particularly helpful with a power bank) but since the operating current will come out of the battery, the battery will never be fully charged.

If both charging status LEDs light up when a charging cable is connected, probably the internal connection to the battery is faulty.

There are four ways to enter configuration mode:

In the first two cases, the throttle will create a wireless network named wiFred-config plus six hex digits taken from the MAC address of the throttle WiFi interface, for example wiFred-config61FB7B and announce its presence under the name config.local as well as creating a captive portal. Any WiFi device with a web browser can connect to that network and open a web browser to point to http://192.168.4.1 or http://config.local.

In the third and fourth case, the throttle will only announce its presence under the name config.local using the Bonjour/Zeroconf-protocol. Any device on the same WiFi network with Bonjour/Zeroconf can use a web browser to access the configuration at http://config.local. See Computer or smartphone to configure wiFred for an explanation what is required to have your device read Bonjour/Zeroconf announcements.

Screenshot of wiFred main configuration page shows the first page you will see when you point a web browser at your wiFred throttle. It is divided into multiple sections explained in the following chapters.

In the "General configuration" section there is only one configuration option: The throttle name. This is a free-form identification string of the throttle. It shows up in the wiThrottle window of JMRI as shown in Screenshot of wiThrottle screen showing one throttle connected and can be used to identify the throttle during configuration.

The "WiFi configuration" section shows a list of configured WiFi networks. The wiFred will connect to any network in this list, choosing the strongest one if multiple configured networks are in range.

Existing entries can be removed by clicking on the "Remove SSID" button in the line of the network that shall be removed.

New entries can be added either by manually entering the SSID and PSK^[2] if required and clicking the "Manually add network" button or by clicking on the "Scan for networks" link which takes the user to the page shown in Screenshot of wiFred "Scan for WiFi"-page.

This page will take a few seconds to load, since the scan for networks has to be completed first. It shows all the networks found during the scan. Networks can be added to the list by clicking the "Add network" button, after entering the PSK^[2] in the field next to it.

The new WiFi configuration will not be activated until the wiFred is restarted, either through a power-cycle or by clicking on the "Restart wiFred to enable new WiFi-settings" link on the configuration page.

Following the WiFi configuration, the section "Loco server configuration" allows configuring the wiThrottle server to which the wiFred shall connect. The default setting - automatically detect server - works well if there is only one wiThrottle server on the network. It will connect to any server announcing its presence on port 12090 through Zeroconf/Bonjour, the result of the Zeroconf/Bonjour-search will be shown here when the wiFred has automatically discovered a server.

Following the "Loco server configuration", there are four identical sections assigned to the four different locomotives which can be controlled with this throttle. Each section consists of the following settings:

If this is set to -1, the corresponding loco is disabled.

By default, if a function key is pressed, the throttle will send the appropriate commands to every loco under control. Under certain circumstances, this may not be desired - the obvious example being a loco in the middle of a multi-unit consist, which should not have lights or ditchlights. So this page - shown in Screenshot of wiFred function handling config page - offers the option to chose between three different settings for every function on each of the four locomotives (one page per locomotive):

The "wiFred status" section shows the current battery voltage, as measured by the wiFred. This is updated on reloading the page, not continuosly.

It also shows the current firmware version(s).

In the wiFred system section of the configuration page, various settings related to the hardware can be changed.

The first setting concerns wiFreds with an On-Off-On direction switch and determines what the center position will do. The options are:

The section concludes with two links:

Overview of devices required to run trains with the wiFred shows the connections between the devices required to run trains using the wiFred.

The symbols in Overview of devices required to run trains with the wiFred symbolize the following parts:

Multiple options for every step or combining these steps are described in the following sections.

A pretty much out-of-the-box solution for a Raspberry Pi is provided by [Steve Todd], which creates its own WiFi network, auto-detects multiple options to interface to a DCC layout and starts a wiThrottle server. It has been tested in the JMRI 4.16 and JMRI 4.20 versions to work with the wiFred, connecting to a Z21 black through both an RRCircuits LocoBuffer USB and a Digitrax PR3 via Loconet.

Although untested so far, adding a [Digitrax LNWI] to a Digitrax system or an [MRC Prodigy WiFi] to an MRC system should allow the wiFred to run locos out-of-the-box as well.

This has been tested on a Windows 7 64Bit laptop computer with a 2.4GHz WiFi card inside the PC.

The wiFred will work on basically any 2.4GHz IEEE802.11b or -g WiFi network that will accept new devices and provide them with an IPv4 address through a DHCP server. It supports open networks or WPA2 encryption, though not WPS.

It has successfully been tested with a FRITZ!Box, a random cable router, multiple public WiFi networks and several software hotspots including Linux hostapd both on a first generation Intel Atom netbook and a Raspberry Pi, the Windows 10 Hotspot and a Windows 7 software as described in Step by step instructions for a Windows computer.

Any PC that can run at least Java 8 will be able to run the JMRI server. Even old 32Bit first generation netbook computers like the 2008 Eee-PC have more than enough computing power for that task. There are JMRI versions for Windows, Linux or MacOS available, so any of these operating systems should be fine.

[JMRI] supports a multitude of different connections to the layout as described in [Supported Hardware]. In general, if a JMRI installation can run a loco on the layout, it’s a simple matter of connecting the JMRI computer to a WiFi access point (if not already connected) and starting the wiThrottle server from the Actions-menu inside DecoderPro.

The wiFred has been tested to work with a LocoBufferUSB or a Digitrax PR3 connected via Loconet to an Intellibox, a Z21 black, a DCS 51 Zephyr xtra or a Minibox 2 DIY DCC central station. It has also been used to run a loco on a SPROG programmer.

Webbrowser, Zeroconf. Avahi. Bonjour (iTunes?). MacOS out of the box? iOS? Android?

For initial configuration of the wiFred, most of the devices mentioned above can be omitted. As shown in For initial configuration, the requirements are very small, only a WiFi capable device with a web browser is required.

Tested with iOS 13 and iOS 14, Android 9 and 10 as well as Firefox on Linux, the initial configuration page is automatically loaded when the device is connected to the wiFred-configXXXX-network.

For regular configuration, once the wiFred has successfully connected to a WiFi network and put into configuration mode, Bonjour/Zeroconf/mDNS support is required to find the device announcing itself as http://config.local. This service is provided on Linux by a software package called avahi, should work out of the box on iOS and MacOS and can be installed on Windows with iTunes. For mobile operating systems, there are apps called Discovery for iOS and BonjourBrowser for Android which not only translate http://config.local to point to the configuration website of the one wiFred on the network that is in configuration mode but also browse all wiFreds currently announcing their presence. User interface of BonjourBrowser, showing two wiFreds active on the network. shows a screenshot of the Android version. Clicking on a device will open a browser to its configuration website.

To support a specialized configuration software, the wiFred will send a UDP broadcast upon successfully connecting to a WiFi network and present its configuration at /api/getConfigXML.

For more information, contact Detlef Born.

The wiFred hardware is centered around an ESP32-S2-WROOM module that controls the LEDs and reads the switches, push buttons and speed potentiometer. It gets its power from a single cell LiPo battery through a 3.3V low drop linear voltage regulator that is activated directly from the loco selection switches combined through a set of diodes. An RC lowpass will delay turning off the wiFred by a couple of seconds.

Optionally, two white 5 mm-LEDs protruding from the top of the PCB can be installed to serve as a flashlight. They are driven by a constant-current source directly from the battery and enabled when pushing the yellow SHIFT key.

The ESP32-S2 also monitors the battery voltage, going into sleep mode when the battery voltage drops too low. This should drop power consumption to a reasonably safe value, even though not as low as it can go when all the loco selection switches are off. Charging the battery can be done through the integrated USB port with two LEDs showing the charging status.

The schematic is split into several pages and can be found in Master schematic sheet with battery connector, charging circuit and power supply to Schematic sheet for user interface (Keys, switches, LEDs, poti and flashlight). It has been created with kicad and is available on the [Github repository for wiFred] along with the PCB design.

To place the ESP32-S2 into firmware flashing mode, a jumper has to be installed on the BOOT pins as shown in Display of boot jumper - left from 0.6 prototype, right from 0.62 rendering when the device is powered up. After entering boot mode, the ESP32-S2 will register as a USB CDC device when connected to a PC and can be programmed through it. Alternately, the serial port at the TXD/RXD pins can be used. The serial port needs to be at 3.3 V-levels like from an FTDI232-device run at 3.3 V.

All files in the software/esp-firmware-subdirectory of the [Github repository for wiFred] need to be placed in a folder, then the main sketch esp-firmware.ino needs to be opened with the Arduino IDE. Settings for the Arduino IDE can be found inside the main file, programming the device should work using the Upload-button in the Sketch-menu. An alternate solution using a pre-compiled firmware and esptool.py may be documented in the future.

All the SMD parts and connectors in List of bottom side components - SMDs and pin headers - for the wiFred PCB from revision 0.6 are located on the bottom side, so they can easily be installed by an automated PCB assembly service. Gerber files and location files will be made available on the [Github repository for wiFred]. They are no smaller than 0805, though, so it should be possible for experienced electronics hobbyists to hand-solder them as well, although the USB-C-connector has a very small pitch.

Then - as shown in List of top side components - ESP32-S2-WROOM and user interface - for the wiFred PCB from revision 0.6 - there is only the ESP32-S2-WROOM module on the top of the PCB and all the switches, push buttons, potentiometer and LEDs. After installing the ESP32-S2-WROOM, the direction switch should be screwed into the PCB with an 8 mm hex nut first, then attached to it’s pads using the cutoffs from the LEDs, and the speed potentiometer should be screwed into the PCB with a 10 mm hex nut before soldering its leads.

For all other switches, push buttons and LEDs, it is recommended to drill the holes in the housing first, then place the parts on the PCB and screw the PCB into the housing before soldering the parts. Holes for the pushbutton switches should be drilled at 3.5 mm diameter. Holes for the LEDs should be drilled at 3 mm diameter and holes for the speed potentiometer at 8 mm, for the direction switch at 6.5 mm diameter. The cutouts for the loco selection switches are best drilled at 1.5 mm and extended to fit with a jigsaw or a sharp hobby knife and a file. The easiest approach is a laser engraved housing - PDF and DXF files of the markings are available on the [Github repository for wiFred] as well.

To form a complete BOM, also include the parts listed in List of components for the wiFred from revision 0.6 excluding electronic parts to solder to PCB which are not soldered to the PCB but used in assembly later on.

After assembling the PCB with all the components, the holes and cutouts in the enclosure most likely will have to be reworked / extended to actually fit the PCB, then the PCB can be screwed into the enclosure with four screws. Afterwards the battery should be connected to the BATT connector making sure the orientation is correct as shown in Connection of battery to P101 on revision 0.6 and up - black wire is GND, red wire is positve and printed on the PCB, then the battery should be glued to the bottom of the enclosure with double-sided tape so it does not collide with any parts on the PCB, particularly the pin headers and the direction switch.

The wiFred hardware is centered around an ESP8266 for the WiFi connection. The ESP8266 communicates through its serial port with an ATMega 328P microcontroller which manages the power, controls the LEDs, reads the loco selection switches, speed potentiometer, direction switch and pushbutton switches for functions and emergency stop. The communication goes through a 2x3 pin header which enables the user to connect a programming cable to the same serial port if removing the jumpers.

Optionally, two white 5 mm-LEDs protruding from the top of the PCB can be installed to serve as a flashlight. They are driven by a constant-current source directly from the battery and enabled when pushing the yellow SHIFT key.

The wiFred is powered by a single cell LiPo battery. The ATMega 328P is connected directly to the LiPo cell, going into sleep mode when no loco selection switch is active, thereby reducing the power consumption to less than 1 µA. The ESP8266 is powered by a low-drop linear voltage regulator with an output voltage of 3 V which is disabled by the ATMega 328P when the device goes into standby.

The schematic is split into several pages and can be found in Master schematic sheet with battery connector, charging circuit and power supply to Schematic sheet including pushbutton switches, loco selection switches, direction switch, speed potentiometer and flashlight LEDs with controller. It has been created with kicad and is available on the [Github repository for wiFred] along with the PCB design.

The PCB has holes in the center of the LED footprints to enable transferring their positions to a StrapuBox housing with a sharp needle or to drill pilot holes with a 1 mm drill. For all other holes, there is a drill jig available which also allows the drilling of pilot holes for the pushbutton switches, the direction control switch and the speed potentiometer. Using the original PCB and drilling jig to transfer the positions of the holes to the housing - better results will be achieved when the PCBs are screwed in position shows the process and its results. Holes for the pushbutton switches should be drilled at 3.5 mm diameter. Holes for the LEDs should be drilled at 3 mm diameter and holes for the speed potentiometer at 8 mm, for the direction switch at 6.5 mm diameter. The cutouts for the loco selection switches are best drilled at 1.5 mm and extended to fit when the PCB is assembled with a jigsaw or a sharp hobby knife and a file.

The remaining assembly is a basic exercise in installing all the components to the PCB, listed in List of components for the wiFred PCB up to revision 0.5. From assembling the prototypes, the suggested order of installing the components is as follows:

To form a complete BOM, also include the parts listed in List of components for the wiFred up to revision 0.5 excluding electronic parts to solder to PCB which are not soldered to the PCB but used in assembly later on.

After assembling the PCB with all the components, the holes and cutouts in the enclosure most likely will have to be reworked / extended to actually fit the PCB, then the PCB can be screwed into the enclosure with four screws. Afterwards the battery should be connected to P101 making sure the orientation is correct as shown in Connection of battery to P101 on revision 0.4 - black wire is GND, red wire is positive and printed on the PCB, then the battery should be glued to the bottom of the enclosure with double-sided tape so it does not collide with any parts on the PCB, particularly P101 and SW313. Finally, both the ATMega 328P and the ESP8266 will need to be programmed with firmware as described in Writing the firmware to revision 0.5 and older wiFreds.

The wiFred prototype hardware is centered around an ESP8266 for the WiFi connection. The ESP8266 also reads the loco selection switches and the battery voltage and communicates through it’s serial port with an ATMega 328P microcontroller which controls the LEDs, reads the speed potentiometer, direction switch and pushbutton switches for functions and emergency stop. The communication goes through a 2x3 pin header which enables the user to connect a programming cable to the same serial port if removing the jumpers.

The wiFred prototype is powered by two AA size battery cells connected to a step-up converter creating 3.3 V for the entire device. As soon as a pair of batteries is inserted into the battery compartment as the symbols inside the battery compartment show, the throttle will boot up and try to connect to a wireless network. The throttle will not be damaged if batteries are inserted wrongly, but it will not work either. Use NiMH- or primary AA cells with 1.2 V to 1.5 V nominal voltage, low self discharge NiMH cells like Eneloop or similar are recommended.

The schematic is split into several pages and can be found in Master schematic sheet with batteries and power supply to Schematic sheet including pushbutton switches, loco selection switches, direction switch and speed potentiometer. It has been created with kicad and is available on the [Github repository for wiFred] along with the PCB design.

The prototype PCB has holes in the center of the pushbutton switch footprints and LED footprints to enable transferring their positions to a StrapuBox housing with a sharp needle or similar, and the position of the loco selection switches can also be transferred to the housing by marking it through the non-copper holes at their ends. Refer to Hints for building revisions up to 0.5 for pictures and more detail, the differences between the AA battery prototype and the LiPo battery revisions are minimal in this aspect.

The remaining assembly is a basic exercise in installing all the components to the PCB, listed in List of components for the AA battery prototype wiFred.

After assembling the PCB with all the components and drilling and cutting the holes and cutouts into the housing, there are few steps left. First, a few protrusions inside the housing need to be removed so the PCB fits properly. Removing protrusions inside the housing so the PCB fits shows how they can be removed easily, remains may be cut off with a hobby knife. Second, new PCB mounting pads need to be installed as shown in New PCB mounting pads made from 3 mm thick Forex PVC. For the prototype, Forex PVC foam was used, cut with a pair of scissors and glued to the housing with superglue, making sure not to be in the way of any components on the PCB, but any kind of easily worked upon material with a thickness of 3 mm can be used, as long as it will take self-driving screws (prototype uses 2.9 mm by 6.5 mm DIN 7981 screws). Third, the two shift keys need yellow paint on the top and the emergency stop key needs red paint - either any kind of paint or a paint marker like Edding 751 will do. Finally, both the ESP8266 and the ATMega 328P will need to be programmed as described in Writing the firmware to revision 0.5 and older wiFreds.

In modular railroading events, particularly of the Fremo-americaN-group, multiple people have evaluated the smartphone throttle solutions and found them lacking a nice, haptical feedback. But the idea of wireless control without locking into a specific vendor and their necessarily expensive equipment found great approval. So a wishlist was compiled to define the requirements for a wireless throttle:

The first prototype versions of the wiFred were built to run from two AA cells, either dry batteries or rechargeable NiMH cells. As described in AA battery first prototype this required some special adaptations of the housing to fit all components. Even then, experience with the prototypes showed the battery compartment cover did not really fit and easily broke when trying to open and close the battery compartment.

So the next versions were built around an integrated lithium battery, losing the ability to exchange empty batteries, but with increased runtime and proper fit into the housing. Recharging of the second generation is done through a Micro USB connector, so a powerbank can extend the runtime of the device when the internal battery is exhausted. Also, the loco selection switches act as more of a power switch than they did with the first prototypes, reducing power consumption to a negligible amount when all locos are deselected.

The latest prototype will switch from a double processor implementation to a single, new ESP32-S2 processor, saving space, reducing the number of components, placing all SMD components on one side of the PCB and enabling direct USB firmware download. It will not contain any new features over the earlier LiPo battery versions, but mainly be easier to build for the hobbyist.

During the development of this wiFred another topic came up in the americaN group of the Fremo, namely wireless clocks with adjustable clock rate for Timetable & Trainorder operations. This led to the spinoff of the [wiClock] project.