miniThrottle Troubleshooting

miniThrottle: A model railroad WiFi throttle.


The miniThrottle is a complex piece of software, which it is hoped will give you flawless operation. But given the variety of hardware and software options it permits, there is a good chance you may encounter issues. So where do you start?!!

NB: some diagnostics won't work on version 0.4, version 0.5 and higher expanded diagnostic capability. Typically the latest development version will cover some known issues and give you additional diagnostic ability. However, as a development version it might break some otherwise working feature. If that happens check back after a week or two to see it it has been fixed or log a bug report in the git pages. Version 0.8 may be out May 2024. Diagnostic options tend to improve with higher numbered releases.


How do I connect to the USB console?The USB console provides the primary diagnotic interface for miniThrottle. It may be reached using the Arduino development environment or terminal emulation software like Putty, Minicom or TeratermPro. Use settings of Speed: 115200, 8 bits data, no parity, 1 stop bit. Using CR/LF line endings is also recommened if your emulation offers that option. Once connected use the help command or help followed by a command name to find your way around. The miniThrottle's serial interface is unique and differs from diagnostics on other projects.
Can I backup or clone my settings?Using the USB console, run the export command. You should be able to cut and paste these to somewhere else. These commands can be run on the same or another miniThrttle to clone it. Before doing a major upgrade, say from version 0.4 to 0.6, use export to back up your settings.
The project doesn't run
  • Connect to the miniThrottle using the USB serial connections, either using Arduino IDE, or a terminal emulation like Putty or TeraTerm-Pro. Reboot the the miniThrottle module and look for errors.
  • run the command "pins" on the console and check you have wired up your display correctly, and your encoder, keyboard, switches and potentiometer are connected to the right pins.
  • Check your throttle and control station are on the same WiFi network.
  • If needed specify the IP address and port number of your control station.
I've got WiFi Connection problems.If your ESP32 module has a built in WiFi antenna etched in the circuit board, try a module with an external antenna. Or try to move closer to your access point, the strength of you access point signal and your distance to it is more important than your distance to the WiThrottle controller. If you want to experiment with your own antenna start by looking at some thoughts on WiFi Antenna for ESP32.
My keypad buttons does strange things
  • Use the USB serial port then type "pins" and enter. check you haven't connected the key pad connector back to front.
  • Use the USB serial port then type "showkeypad" and enter, then press the keypay bottons. See if a pattern of mapping is shown. Then either rewire you keypad rows and columns to match, or change your keypad mapping in miniThrottle.h and recompile.
  • Replace the keypad if it is faulty.
When I compile I see ugly errors like:
expected unqualified-id before '(' token
#define max(a, b) ((a) > (b) ? (a) : (b))
Try using the development branch and defining the following in miniThrottle.h:
The compile error is caused by an incompatibility between lcdgfx and the httpclient library on version 2 of the Arduino ESP32 compiler. By disabling this feature you disable the ability to download configuration files or OTA updates to your throttle. It is not expected that will pose much inconvienence to the average user, you will need to use version 1.8 of the compiler if you wish to enable it.
This is the slowest thing on the planet!!There is a known problem when using version 2 of the Arduino IDE and a SDD1306 display. Screen refreshes will take 2 or 3 minutes or more! Avoid using version 2 of the Arduino ESP32 compiler and the SDD1306 display. Either select a different display type or use version 1.8 of the IDE.
How can I see if commands are going between my throttle and command station?Two options:
  • Use the USB serial port and type "showpackets" and enter. Use the throttle, the commands and responses should be displayed. The USB option requires you are teathered to your throttle.
  • Enable the temporary diagnostic port via the web page and then use a "telnet" program like Putty or TeraTermPro to connect to your throttle, then entering the command "P" (packets) will show your network traffic.
Can I monitor communication with the control station if miniThrottle is bolted away in a box or under my benchwork?Yes, perhaps. V 0.6a and later has a "diag" port that can be enabled from settings on the web interface. Once enabled, you can telnet to the diag port to monitor control station commands. This diagnostic port won't restart when miniThrottle is restarted, it is a temporary facility.
miniThrottle crashes and rebootsThat is not intended! Did it work previously? Did you change a setting? Does it always crash when you do the same thing? Now to figure out what went wrong by increasing the debug level prior to the next crash. To do that run "debug 3", the debug levels persist reboots and are:
  • debug 0 - Minimal
  • debug 1 - Default / recommended
  • debug 2 - Extra info, eg shows WiFi networks, if and when checked
  • debug 3 - Noisy, shows what major program routines are invoked
Including the last 5 to 10 lines of debug is useful in your bug report.
How can I check what data is loaded?If you an to see the raw data about your rosters etc, try "locos", "turnouts" or "routes" at the USB console. If you want delve deeper check "help dump" and "help nvs" for descriptions of deeper diagnostics.
When I select a route there is a time when it is inconsistent. Is that a bug?It is intentional. The route is being set up. Parts of it is set up and part is not. Trying to make use of it in this state can result in an accident if a turnout position changes while a train is passing over it.
Can I test the throttle without connecting to a control station?No not really! miniThrottle relies on getting control station responses to confirm settings. miniThrottle works on a design principle of getting feedback from the control station. You are not going forward at 60% speed until the control station has confirmed it. A side effect of that is sometimes miniThrottle may appear to lag in response compared to throttles that simply assume their requests will be obeyed and set a speed without having any confirmation.
I am using miniThrottle as a WiThrottle relay, my speed settings are diplayed briefly in EngineDriver then drop to zero.Check you have the track power on, without track power, your speed will be zero. Also check your serial connections between miniThrottle and DCC-Ex are correct. Without proper communications you'll not be able to move.
I get no joy from code or soldering.
I just want run trains.
Avoid projects like this one. Buy a commercial product. On the other hand, you may get a kick at looking at your own customised throttle and thinking "I did that!" - in that case it will be worth the effort.
The throttle menu is missing optionsBy default the menu only shows options which are usable. You may need to check you have track power applied, or refresh the menu by going back one menu level. CV Programming is not possible using WiThrottle, you need to use the DCC-Ex protocol for that.
This looks more complicated than other throttle projects!There are several other throttle projects that create throttles with less code or less soldering. But check if any of these are important to you:
  • Support of more than one protocol: WiThrottle and DCC-Ex.
  • Support for either WiFi or Serial (teathered) connectivity to the control station
  • WiFi information for up to 6 networks can be defined in advance allowing you to move seamlessly between different networks when operating on different layouts.
  • Support of bidirectional communications with the control station. Many other projects just issue commands to the control station and assume their command will be obeyed. MiniThrottle waits for a response from the command stantion to confirm what was asked of it was done. Sometimes a command station can't fulfil a request that was sent to it. This also gives you feed back your request was received.
  • Support for a variety of different hardware and layouts. By allowing a selection of keyboards, displays and switches, additional complexty is added.
  • Text based console interface. This allows a level of configuration and diagnostics that some other projects do not support.
  • Optional web configuration interface: Not uncommon in micro-controller projects, but this does allow another level of customisation.
  • Optional relay facility. Not too many throttle projects offer a similar feature.
So does that mean this is better than other Arduino DCC throttles?No! Depending on what and how you are trying to do things others maybe better. Look at build complexity, and features. Then compare and decide what you want to do. Many of these have been around for years and have wide support bases. miniThrottle has only been around since early 2022.

Here are some examples, although not an exhaustive list and not in any order of preference:

Thank you for visiting camelthorn.cloudHome