miniThrottle, Software download & compile

miniThrottle: A model railroad WiFi throttle.


Software download

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.

To reduce confusion, older versions have been removed from this page.

VersionStatusGithubZip fileFile DateComments
0.8CurrentgithubV0.8 zip 03-May-2024Updated version

Software compilation

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.

Most of the miniThrottle can be customised by the builder - importantly it contains the pin definitions for your build. eg: which pin is used to indicate track power is on. The table below shows major sections to look out for in this file. If you specify more than one function for the same pin, the miniThrottle will stop its boot process and indicate this. Aside from having to fix the error and reflash the module, no damage will have been done.

Config-ItemComments
Display miniThrottle has been tested using several display types, and these definitions are also located in the miniThrottle.h. Look for "NODISPLAY" and there will be a list of supported displays. - Uncomment just ONE of these. Further down there will be some related definitions, if you uncommented "#define ST7735" , look for the line "#ifdef ST7735". The next few lines to the "DISPLAYNAME" line define the pins to use to communicate with the display. Leave the DISPLAYNAME and successive lines unchanged.
Display Colour You may want to change the default colour scheme if using a colour display. Look for the line "#ifdef COLORDISPLAY", and you will find colour definitions. The sequence of numbers is in the sequence Red, Green, Blue. And the values are between 0 and 255 inclusive, where 0 means none of this colour, and 255 indicates using the maximum value of this colour.
Analogue Displays There are 2 places to look for these:
  • INDICATOR LEDS
  • ANALOGUE VOLT METER OUTPUT
Keypad To select the matrix keypad to use, look for the line "#define keynone", and uncomment the ONE configuration you want to use. If you have selected "#define key3x4", then search for the section starting "#ifdef key3x4". This defines the row and colum geometry, which pins are used to connect the keypad and what each button press defines. Sometimes when you connect your peypad for the first time, you may find your columns transposed, either change your wiring or swap your pin difinitions and recompile. One of the quirks if using to potentiometer throttle, is you may want to turn it off so there are lines here for when the potentiometer throttle is used and when it is not.
Other input Look for the section "ENCODERS AND SWITCHES" - the pin assignments for these will be found here.
Network & name Look for the section "NETWORK DEFAULTS" - the default network settings are defined here.
Web Server Look for the section "WEB CONFIGURATION" - the definitions will be found here, including the webserver port and initial admin user credentials. Once running you can change your admin user's credentials as often as you like.
Serial connectionUsed for connecting DCC via serial port. Look for the section "DIRECT SERIAL CONNECTION" - This will define which pins to use to connect tio DCC, these do not have to (but can be) the ones labeled Tx2 and Rx2. You will also define things such as timeouts and what the defaults for the fast clock service should be.
Other settings It is suggested you scan the file for other settings that may be of interest. Some of these would just be debug settings, but there are some others such as "FUNCOVERLAY" that could be useful.
Partition scheme While not defined in monoThrottle.h, it is also possible to use a customised partition scheme for your Esp32 flash memory. To do this copy the "partitions.csv.example" to "partitions.csv" and edit the partion scheme, or use the default one.
Additional Fonts From version 0.7 additional large fonts are available. These are not useful for small pixel geometry displays and so are not part of the standard build. However, several fonts are available for 12x24 and 16x32 pixels per character geometries. Including them will also result is a slightly larger build to flash to the ESP32. To use a font, retain the "a_font_" file name, bit just rename it to end in a ".ino" suffix.
So that for example a_font_12x24.ino.alt3 becomes a_font_12x24.ino

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
0.11.5
$ arduino-cli lib install "ESP32encoder@0.9.1"
lib version 0.11.5 for release 0.7i and later
display support:lcdgfx1.1.4$ arduino-cli lib install "lcdgfx"

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. If you are using your own partition scheme then omit the ",PartitionScheme=min_spiffs" part of the compile line above.

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[] = {



Thank you for visiting camelthorn.cloudHome