miniThrottle: A model railroad WiFi throttle.
↓↓ Dig deeper ↓↓
MiniThrottle is a wireless (WiFi, for DCC-Ex or WiThrottle) or serially connected (DCC-Ex) model train throttle.
The project is in a sense "incomplete". Many final design decisions are left to the constructor. This allows the builder for example to:
See Builders Notes page for some build suggestions.
MiniThrottle can connect either directly to a DCC-Ex controller using either DCC-Ex or WiThrottle protocols, or it can connect to JMRI using WiThrottle protocol. If connecting to DCC-Ex, the DCC-Ex unit should have a suitable WiFi interface configured OR allow miniThrottle to access DCC-Ex via serial connection. By using DCC-Ex protocol rather than WiThrottle on a DCC-Ex controller, allows miniThrottle to access the programming track and have internally defined locomotive rosters and turnouts. A future version of miniThrottle may allow miniThrottle to relay multiple WiThrottle connections to DCC-Ex if connecting to Dcc-Ex via a serial connection.
miniThrottle uses the expression "turnouts" in preference to either "points" or "switches". The intention is to avoid ambiguity: Points may refer to a location on a cartesian plain or a location in program code. Switches too could refer to an electrical switch or a programming construct.
The software can be downloaded from github or as a zip file which may be updated less regularily. When selecting a version to use, please be cautious if selecting odd numbered development releases. These may have half implemented features which don't fully function or have partial functionality. They may even break some previously implemented features.
Version | Status | Github | Zip file | File Date | Comments |
---|---|---|---|---|---|
0.4 | "Stable" | github | V0.4 zip | 15-Jun-2022 | Original public release version |
0.5 | Development | Same as above but use "development" branch | V0.5 zip | 02-Feb-2023 | Unstable development work Adds web management interface Adds WiThrottle relay to serially attached DCC-Ex Rework of include file should simpify initial configuration Timeline: expect stable feature set Feb/Mar 2023 |
Once downloaded, the first step is to configure the software to match the hardware you want to use. To do this edit "miniThrottle.h" - initially copy this from "miniThrottle.h.example". This will include the display type selected, keypad geometry, default network etc. In order to reduce component count the keypad is attached directly to the esp32 module.
To compile, configure Arduino IDE to support the esp32 processor as described at either:
Note: Using the links in the above instructions you will install the ESP platform version 1. A version 2 of the ESP platform is available, but MiniThrottle won't compile with that version at this stage. There are some library features used by MiniThrottle which are unfortunately not compatible with the newer development libraries.
Add the libraries below. Using the GUI (Graphical User Interface) "Tools" > "Manage Libraries...". Or if using the CLI (Command Line Interface), the instructions in the table.
Function | Library | Version | Arduino CLI installation |
---|---|---|---|
keypad support: | keypad | 3.1.1 | $ arduino-cli lib install "keypad" |
encoder support: | ESP32encoder | 0.9.1 | $ arduino-cli lib install "ESP32encoder@0.9.1" |
display support: | lcdgfx | 1.1.4 | $ arduino-cli lib install "lcdgfx" |
Note: From development version 0.5a (18-Nov-2022), it is possible to compile miniThrottle witout the above 3 libraries, but only if NODISPLAY is configured in miniThrottle.h. The purpose of this is to create a "headless" relay device that effectively replaces the ESP8266 WiFi interface on a DCC-Ex controller. Such a device has no display, keypad or buttons. However, a relay could still operate without NODISPLAY, ie relay and be a throttle with a display and user input. The relay connects to DCC-Ex over the serial connection, has WiFi enabled, and has a RELAYPORT defined. Optionally it may also have the web interface enabled.
A wide variety of compiler settings will work, but on the prototype units, the following were used for the prototype build:
If using the CLI (Command Line Interface) of the Arduino development environment: (ignore this if using the graphical interface)
mkdir miniThrottle_bin arduino-cli compile --output-dir ./miniThrottle_bin --fqbn esp32:esp32:lolin32:CPUFreq=80,PartitionScheme=min_spiffs ESP32_miniThrottle arduino-cli upload -p /dev/ttyUSB0 --fqbn esp32:esp32:lolin32 ESP32_miniThrottle
A CPUFreq=240 option is preferred if you intend operating MiniThrottle as a WiThrottle to serial relay.
Once flashed, connect to the serial console 115200, 8 bits, No parity, 1 stop bit. If using a terminal emulation such as Putty or TeraTerm to access the console set your line terminations to LF. The console has a "help" function which will list supported commands. At this point the supported wireless networks can be configured. No web configuration interface exists and initial configuration is via the serial console.
Note to Serious geeks: It is possible to add fonts if you require more than are provided in the project. See adding fonts to LCDGFX for instructions on how to convert a fixed Linux font for use by lcdgfx. The resultant output should include a define for "CUSTOM_FONT" and the name of the font variable. Follow the example fonts in the project and name your font file so that it appears ahead of where it is used in the project.
#define CUSTOM_FONT const PROGMEM uint8_t font_12x24[] = {
Part | Description | Mandatory |
---|---|---|
esp32 | Any esp32 module, but consider one with built in battery support if building a hand held unit. | Yes |
Display | One of displays supported by LCDGFX library. sdd1306, sdd1327, st7789 or ili9341 used in testing | Recommended |
Rotary Encoder | Rotary encoder with push switch function | Recommended |
Keypad | Any matrix key pad. Membrane key pads recommended at these are compact and can be cut. | Recommended |
Potentiometer | 10K Slide or rotary for throttle. If slide, then consider one with a longer lenth of travel. | No |
Reversing lever | Single throw two pole switch. Having a center off position is useful for a brake position. | No |
indicator LEDs | Up to 4 to indicate various states. Note different color LEDs will require different current limiting resistor values. | No |
Voltmeters | Up to 2 3V voltmeters to use as speedometer or brake indicators. | No |
Case | A suitable housing to include the options selected | No |
Prototyping board | For ease of mounting completed project and ease of wiring | No |
Main on/off switch | A suitable toggle, rocker or key switch | No |
Wiring | Used to connect components together | Yes |
Battery | 3.7V rechargable battery for untethered operation | No |
Misc | bridge rectifier, 5V buck converter for non-USB or power >5V | No |
Misc | PWM controller to control screen brightness on the Blk pin of some displays | No |
Using a module based on the esp32 processor is recommended. Designing your own circuit board is probably more detail than most hobbists would care to do. Some modules support rechargable batteries or built in displays. Having a battery in your controller makes it ideal for handheld units.
Aside from the esp32 processor, this is the only mandatory hardware. However, one of a number of displays can be selected, as long as it is supported by the lcdgfx library. Any display supported by the lcdgfx library should work, but not all have been tested in prototypes. A minimum resolution of 128x64 pixels is recommended. For example:
Type | Resolution | Color | Rotatable |
---|---|---|---|
SSD1306 | 128x64 | Mono | 0, 180 degrees |
SSD1327 | 128x128 | Mono | None |
ST7735 | 128x160 | Color | 0, 90, 180, 270 degrees |
ST7789 | 135x240 | Color | 0, 90, 180, 270 degrees |
ILI9341 | 240x320 | Color | 0, 90, 180, 270 degrees |
When considering a display, think of the font height and the distance at which it is going to be read at. Bigger fonts make for more comfortable reading. It is recommended that your font height should be no less than 1/200th of the reading distance, and 1/150th of the distance may be more readable.
This can be used to navigate menus and adjust locomotive speed. Use a 20k pull up resistor for encoder and encoder switch pins connected to the ESP32 pins. Other encoder pins are connected to ground. Effectively to MiniThrottle the encoder becomes a simple "keypad" with up, down and select buttons. Thus the input from another keypad can override or duplicate the effect of the rotary encoder.
Any one of a number of key pads can be selected. Membrane keypads are highly recommended, both because of the variety of them, and the ability to trim them using scissors or craft knife. These keypads tend to come with a ribbon cable connector which can connect directly to the esp32. They have a row and column matrix, such that every key can be mapped by its row and column reference. Typically the keys are mapped to something related to their legend, but can be mapped to any single character function.
On a newly built system, check the keypad mappings produce the characters you expect by giving the "showkeypad" command at the serial console. By pressing keys or buttons, encoder etc, you can ensure each key press gives the expected value shown in the "Function" column of the table below. Then either correct the wiring or update the keypad mapping in "miniThrottle.h", recompile and reflah the micro controller.
Functions and their meanings are as follows. Since some keys support different function when in menu or driving mode, quite a lot of functionality can be had even from very simple keypads.
Function | Typical Key | Effect |
---|---|---|
0 | 0 | Function/Numeric Zero, or ESC in menus |
1 | 1 | Function/Numeric One |
2 | 2 | Function/Numeric Two, or up arrow in menus |
3 | 3 | Function/Numeric Three |
4 | 4 | Function/Numeric Four, or left arrow in menus |
5 | 5 | Function/Numeric Five, or Select menu option in menus |
6 | 6 | Function/Numeric Six, or right arrow in menus |
7 | 7 | Function/Numeric Seven |
8 | 8 | Function/Numeric Eight, or down arrow in menus |
9 | 9 | Function/Numeric Nine |
* | * | Toggle Bidirectional Mode |
# | # | Cab menu - when driving locomotives, or Select menu option in menus |
X | F1 or A | Select Function 10-19 |
Y | F2 or B | Select Function 20-29 |
E | ESC | Escape, back one menu level |
S | ENT | Select/Enter, Select menu option |
L | Left-Arrow | Change direction to reverse, or ESC in menus |
R | Right-Arrow | Change direction to forwards, or select in menus |
U | Up-Arrow or C | Increase speed, or previous option in menus |
D | Down-Arrow or D | Decrease speed, or next option in menus |
P | * | Potentiometer on/off, bypass potentiometer when driving in potentiomenter enabled systems |
B | None | Brake |
A 10K or 20K potentiometer wired as a voltage divider can be used with the wiper (Generally labelled 2) connected to the esp32 and the remaining pins (1 and 3) connected between 3.3v and ground. If using a slide potentiometer, one with a longer length of travel will work better than a shorter one, as the a shorter length will be more sensitive to any movement. The esp32 analogue to digital conversion tends to flatten out at about 3v, so you may like to consider placing an additional resistor that is about 10% of the potentiometer value between it and the 3.3v supply. The pins 32, 33, 34, 35, 36 and 39 are candidates for potentiometer use.
This uses 2 pins only one of which should be brought to ground potential at any time. By using a double pole single throw switch with 3 positions this permits a reverse lever with forward, brake and reverse positions.
Note the reversing lever is effectively a keypad with "L" (Left), "B" (Brake) and "R" (Right) functions. Thus direction can be overriden with keypad entries from a membrane keypad, or by using the rotary encoder "keypad" in bidirectional mode.
A number of selections can be indicated
This is implemented as a 3V voltmeter between the esp32 I/O pin and ground. One of pins 25 or 26 may be used. Replace the voltmeter scale with a more appropriately labeled one of your own. Full scale deflection is at 100% throttle.
This is implemented as a 3V voltmeter between the esp32 I/O pin and ground. One of pins 25 or 26 may be used. Replace the voltmeter scale with a more appropriately labeled one of your own.
It is a very rough brake pressure simulator, pressure builds to a maximum over a few seconds, and drops quickly when slowing down. On a real train the pressure may take several minutes to build up and generally won't get used as quickly. This simulation doesn't simulate using brake while travessing an incline. However, it may help awareness in slower steady braking and just be a "fun" addition to a throttle system.
The full list of commands can viewed using the "help" or "help summary" commands at the serial console. The name of a command can be given as a parameter to help if you want more details about a specific command, eg: "help add". The console is case sensitive so that "A" and "a" are different. Some of the more useful commands are shown below:
In a WiThrottle system, the JMRI computer will provide your throttle with lists of locomotives, turnouts or routes. Although DCC-Ex allows rosters, and switches to be stored, many users may find defining them in miniThrottle easier to manage. miniThrottle does not check DCC-Ex for roster or turnout information set in the DCC-Ex controller. When using WiThrottle the programming of CVs is done though JMRI web interface, the wiThrottle interface does not allow for easy CV programming. But they can be set using miniThrottle and DCC-Ex.
After power on the MiniThrottle searches for a WiFi network and server to join. Pressing a keypad key during this time will take you to the same configuration menu as can be accessed when the MiniThrottle is running. Once connected the control station is given a few seconds to respond and identify itself. If no identification is received the the default protocol is selected. At which point the main menu is displayed.
Locomotives Turnouts Routes Track Power CV Programming Configuration
This presents a menu where locomotives can be either selected from the roster or controlled by their ID number. Once a locomotive has been selected, a display like that shown on the right will display, where direction, speed and functions are displayed.
When driving pressing the "#" key will take you to a "Cab Control Menu". The add and remove loco options allow the same commands to be sent to multiple locomotives at the same time without using advanced consisting. NB: The Cab menu can only be accessed if the locomotive has stopped. The first locomotive selected can only be removed if it is the only, or last remaining, locomotive selected. This Cab menu has the following options:
Add Loco Remove Loco Turnouts Routes Return
This menu is used to select a turnout by name and set it either Closed or Thrown.
This menu allows a route to be selected. It allows a particular sequence of turnouts to be set.
This is only operates with DCC-Ex protocol. If using WiThrottle, it is expected that the JMRI computer will be able to program locomotive CVs. This option allows locomotives to be configured with a very simple mix of miniThrottle and DCC-Ex only.
Read Loco Addr Read CV Byte Write Loco Addr Write CV Byte Write CV Bit Prev. Menu
Bidirectional Mode CPU Speed Font Info Protocol Restart Rotate Screen Server IP Server Port Speed Step Prev. Menu
When driving locomotives there are 2 modes of operation, best summarised as follows:
Hardware | Standard Mode | Bidirectional Mode |
---|---|---|
Encoder | Rotating anti-clockwise reduces speed to 0%. Rotating clockwise increases speed upto 100%. | Rotating anti-clockwise reduces forward speed or increases reverse speed. Rotataing clocwise reduces reverse speed or increases forward speed. |
Keypad | Down button reduces speed to 0%. Up button increases speed upto 100%. | Down button reduces forward speed or increases reverse speed. Up button reduces reverse speed or increases forward speed. |
Potentiometer | Moved to one side reduces speed to 0%. Moved to the opposite side increases speed upto 100%. | Center postion is idle. Moved to either extreme is full throttle in the respective direction. |
Note: if including a potentiometer in your build, it is recommended that a "P" button is configured on your keyboard (if using one). This allows the potentiometer to be enabled or disabled, so that it does not over ride any speed / direction settings set from keypad or encoder.
Thank you for visiting this website | Home |