miniThrottle, a DCC-Ex and WiThrottle throttle

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.

Prototype miniThrottle with optional speed and brake pressure indicators, keypad and large display. miniThrottle uses the Arduino IDE to program an esp32 micro controller to act as DCC throttle and/or control station.

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.

Diagram showing WiThrottle and DCC-Ex connectivity for miniThottle DCC throttle

Software download and compilation

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.

By downloading from this site you accept the conditions of use.

VersionStatusGithubZip fileFile DateComments
0.4"Stable"githubV0.4 zip 15-Jun-2022Original public release version
0.5DevelopmentSame as above but use "development" branchV0.5 zip 02-Feb-2023Unstable 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
0.5Pre-CompiledSee Precompiled page

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.

FunctionLibraryVersionArduino CLI installation
keypad support:keypad3.1.1$ arduino-cli lib install "keypad"
encoder support:ESP32encoder0.9.1$ arduino-cli lib install "ESP32encoder@0.9.1"
display support:lcdgfx1.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.

const PROGMEM uint8_t font_12x24[] = {

Hardware Selection

Bill of Materials

esp32Any esp32 module, but consider one with built in battery support if building a hand held unit.Yes
DisplayOne of displays supported by LCDGFX library. sdd1306, sdd1327, st7789 or ili9341 used in testingRecommended
Rotary EncoderRotary encoder with push switch functionRecommended
KeypadAny matrix key pad. Membrane key pads recommended at these are compact and can be cut.Recommended
Potentiometer10K Slide or rotary for throttle. If slide, then consider one with a longer lenth of travel.No
Reversing leverSingle throw two pole switch. Having a center off position is useful for a brake position.No
indicator LEDsUp to 4 to indicate various states. Note different color LEDs will require different current limiting resistor values.No
VoltmetersUp to 2 3V voltmeters to use as speedometer or brake indicators.No
CaseA suitable housing to include the options selectedNo
Prototyping boardFor ease of mounting completed project and ease of wiringNo
Main on/off switchA suitable toggle, rocker or key switchNo
WiringUsed to connect components togetherYes
Battery3.7V rechargable battery for untethered operationNo
Miscbridge rectifier, 5V buck converter for non-USB or power >5VNo
MiscPWM controller to control screen brightness on the Blk pin of some displaysNo


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.

A sample of esp32 based processors modules suitable for use with miniThrottle DCC throttle


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:

SSD1306128x64Mono0, 180 degrees
ST7735128x160Color0, 90, 180, 270 degrees
ST7789135x240Color0, 90, 180, 270 degrees
ILI9341240x320Color0, 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.

A sample of displays showing a range of sizes suitable for use with miniThrottle DCC throttles

Rotary Encoder

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.

FunctionTypical KeyEffect
00Function/Numeric Zero, or ESC in menus
11Function/Numeric One
22Function/Numeric Two, or up arrow in menus
33Function/Numeric Three
44Function/Numeric Four, or left arrow in menus
55Function/Numeric Five, or Select menu option in menus
66Function/Numeric Six, or right arrow in menus
77Function/Numeric Seven
88Function/Numeric Eight, or down arrow in menus
99Function/Numeric Nine
**Toggle Bidirectional Mode
##Cab menu - when driving locomotives, or Select menu option in menus
XF1 or ASelect Function 10-19
YF2 or BSelect Function 20-29
EESCEscape, back one menu level
SENTSelect/Enter, Select menu option
LLeft-ArrowChange direction to reverse, or ESC in menus
RRight-ArrowChange direction to forwards, or select in menus
UUp-Arrow or CIncrease speed, or previous option in menus
DDown-Arrow or DDecrease speed, or next option in menus
P*Potentiometer on/off, bypass potentiometer when driving in potentiomenter enabled systems

A sample of membrane keypads, miniThrottle DCC throttle can be flexible enough to accommodate any one of these

Throttle potentiometer

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.

A sample of potentiometers, shorter slide or rotary potentiometers can be expected to be more sensitive to small adjustments to position. Longer ones may therefore give a nicer/smoother throttle control.

Forward/Reverse switch/lever

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.

Indicator LEDs

A number of selections can be indicated

Speedometer (3V voltmeter)

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.

Brake Pressure Indicator (3V voltmeter)

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.

Serial Console

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:


Display set up

Wireless set up

DCC-Ex Only

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.

It is possible to operate miniThrottle DCC/WiThrottle throttle with a very low component count

Using the MiniThrottle

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.

Main Menu

Track Power
CV Programming
Locomotive driving display of a miniThrottle DCC throttle


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


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.

CV Programming

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
Rotate Screen
Server IP
Server Port
Speed Step
Prev. Menu

Operational Modes

When driving locomotives there are 2 modes of operation, best summarised as follows:

HardwareStandard ModeBidirectional 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 websiteHome