miniThrottle Troubleshooting
miniThrottle: A model railroad WiFi throttle.
Preamble
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?!!
Note the command line commands use lowercase commands, but some parameters may use capitals. If you find using the command line clumsy or counterintuitive, then please use the web interface instead!
Command line
Serial connection from either the Arduino IDE or a terminal emulator (Putty, Teraterm etc), 115200, 8 bits, no parity, one stop bit. Commands are sensitive to CAPS-lock or additional characters being added. Use help command to list all commands, or look up specific commands, eg using green for users commands, and yellow for miniThrottle's responses:help protocol
Running permanent settings without parameters prints current settings:
protocol {withrot|dccex}
Select default protocol to use
PROTOCOL DCCEX
Command not recognised.
protocol dcc-ex
protocol should be one of: withrot, dccex
protocol
Default protocol is WiThrottle
protocol dccex
protocol
Default protocol is DCC-Ex
Web interface
For many users using the web interface is a good configuration option. Not only is it easier to use, but you do not have to be tied to the miniThrottle by a USB cable. Simply use your web browser to access your throttle, eg: http://192.168.4.1 There are two networks that are of interest when connecting to the web interface:
- The access point or "AP" network: When minithrottle first starts it will create an access point named after itself. This will have an address of 192.168.4.1 - you can connect to this address after joining your miniThrottle network. Having this network, means you can configure the miniThrotlle without ever having to use the command line interface. In most instances you can turn off the AP network and just use the Station (STA) network after initial configuration. You must turn off the AP if you want to access any other device on a 192.168.4.<anything> STA network. Otherwise your AP and STA networks will clash and are likely to have IP addresses in common - making it impossible to determine which is the right device to be sent commands.
- The station or "STA" network: Once you have provided your throttle with the network ID (or SSID) and its password you should be able to connect to your throttle via this network. Your throttle will be whatever you home or club's router or access point allocates to it. Often this will stay the same, but it may vary.
Since by default miniThrottle will run mdns, for some systems such as Android or Apple, you can connect using the throttle's name - dot - local address. With the example in the screenshot, http://woodthrottle.local would work. Since the web interface uses an unencrypted link, there maybe a warning that your connection is insecure. Given you aren't (and should not) be putting your banking details in via this link, this warning can be ignored.
When you select options to configure using the web interface, you will be prompted from a user name and password. Unless you have changed them, the defaults will be:
- User name: admin
- Password: mysecret
Troubleshooting
| Symptom | Suggestion |
|---|---|
| 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 |
|
| 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 |
|
When I compile I see ugly errors like: C:\Users\enfield\projects\ESP32_miniThrottle\webserver.ino: In function 'void mkWebDeviceDescript(WiFiClient*)':
C:\Users\enfield\projects\ESP32_miniThrottle\webserver.ino:1748:6: error: 'spi_flash_get_chip_size' was not declared in this scope
1748 | spi_flash_get_chip_size() / (1024 * 1024));
| ^~~~~~~~~~~~~~~~~~~~~~~
exit status 1
Compilation error: 'spi_flash_get_chip_size' was not declared in this scope
| |
| Compilation error: 'spi_flash_get_chip_size' | Check that you are not using verson 3 of the ESP32 board manager. If you are, downgrade to version 2. In your IDE go to the "Tools" drop down and find "boards manager". Now search for "ESP32", and in the "esp32 by Espressif" you will see a dropdown selection. This may have a number like "3.0.3", select the most recent version 2, eg "2.0.17" and install that. Don't upgrade your boards for esp32 while you want to compile miniThrottle. |
When I compile I see ugly errors like: expected unqualified-id before '(' token
#define max(a, b) ((a) > (b) ? (a) : (b)) | Define the following in miniThrottle.h:#define NOHTTPCLIENT 1The 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:
|
| 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 reboots | That 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:
|
| 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 options | By 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:
|
| 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:
|
Connectivity Issues
This is potentially a big topic of its own, so will be dealt separately to general troubleshooting.
Checking data flow
One of the primary tools for this is using the "showpackets" command at the serial console. This allows you to verify miniThrottle is attempting to send data and the format it is in. You will also be able to see what data is being returned and the format it is in. If data is not flowing in both directions using the same protocol, then there is no controlling of trains!
There will be arrows indicating the direction of data flow:
- --> = Data from miniThrottle to remote
- <-- = Data from remote to miniThrottle
- Dcc-Ex: The data is encapsulated in less-than < and greater-than > signs
- WiThrottle: The lines normally start with an alpha character - Some data may also be separated by square bracket sections: ]\[ or brace sections }|{
Checking data flow wirelessly
Note: Version 08 had a bug with the way the diag port works which would cause the miniThrottle to reboot. This is corrected in version 0.8a - available via git only. Please check your miniThrottle version before using!
Normally the diag (diagnostic) port is not running, to start it you can use the "diag" command at the command prompt, or use the "Main Config" in the web interface.
It is a useful diagnostic toll if your miniThrottle is built into a closed box or under some benchwork.
To access it use a terminal emulation (eg putty or TeraTermPro) to connect to your miniThrottle specifying either a raw or telnet protocol.
Pressing "p" and "enter" will start and stop the display of packets to your teminal emulation.
You can also get a dump of important memory structures to see what data is loaded.
When scanning networks (wifi scan option), this takes a few seconds and may lead to a temporary loss of network connectivity. The higher the number the stronger the signal. -20 is much stronger than -80.
Serial connections
This may apply to both directly attached serial to the miniThrottle, or when using a serial to TCP/IP (or WiFi) adapter on your control station. Both sender and receiver must use the same speed and flow control settings - Typically 115200 bits per second / baud, 8 bits of data, no parity, 1 stop bit. If random bits of junk get passed back and are shown in showpackets, then you probably have mismatched speed settings. If no data is flowing check you have transmit in either side connected to the receive pin of the opposite side.
WiFi
Initially a freshly built miniThrottle will create a Wifi access point named after itself, and no password. You can connect a tablet of laptop to this WiFi network and access http://192.168.4.1 on this network to configure other wireless settings. It is recommended that unless you are using this miniThrottle as a relay, that to turn off this access point. The default user and password for web admin are "admin" and "mysecret" - it is suggested you change these.
There are some diagnostics to run at the serial prompt, note most of these can be run with a parameter to change the setting. Note all commands are run lower-case, do not use capital letters:
- config - Check if miniThrottle is connecting to anything - if connected, your wifi should be right.
- wifi - Check the WiFi network is listed and has the right password. If you need to specify a WiFi password note you need to specify an index, SSID and password as parameters, eg:
wifi 1 BrocolliSoup CabbageIsBetter
wifi - wifimode - Typically once configured, most miniThrottle builds are axpected to run in sta mode only. But AP or both modes can be useful if running a relay.
wifimode sta
Note in AP (access point) mode miniThrottle uses the 192.168.4.1 address. if you wish to connect to another network device with the same address, you must operate in STA (station) mode.
restart - wifiscan - If no WiFi network is connected to, this command will allow you to scan for networks. If may take several seconds for the scan to complete.
- protocol - Use this to set miniThrottle to use the correct protocol. Early releases tried autodecting the protocol, but this was unreliable, and setting your preference manually proved better.
protocol withrot
restart - server - When operating in WiThrottle mode, minithrottle can often autodetect the remote server using mdns, but if this is not working or using DCC-Ex over WiFi, then the server will need to be set manually. If the server does not autodect a server, it will scan for servers and ports by sequentially working through the server list. If you do not want miniThrottle to autodect a server, turn mdns off. To set both IP address and port specify both on the command line as space separated values eg:
server 1 192.168.1.172 2570
- mdns - enable/disable mdns search facility to search of WiThrottle servers, or manually search for a service, eg
mdns on
Note the mdns command can search what services are running on other network attached devices. It does not list what is running on the searching device.
mdns _withrottle
mdns _http
help help wifi help wifimode
| Thank you for visiting camelthorn.cloud | Home |