miniThrottle, a DCC-Ex and WiThrottle throttle

↓↓ Dig deeper ↓↓

• Site Menu
  • HydraFerret Configuration
    • Introduction to HydraFerret
    • Installing on ESP32 module
    • Electrical wiring
    • Module configuration
    • Network configuration
    • Configuring xymon
    • Graph definitions
    • Sending data to xymon
    • Command line interface
    • Creating alerts
    • RPN calculator
    • Upgrading "over the air"
    • Troubleshooting
  • HydraFerret Sensor details
    • adc - Analog to digital conv
    • bh1750 - Light meter
    • bme280 - Temperature, humidity
    • counter - Counter
    • css811 - CO2 and TVOC
    • ds1820 - OneWire temp sensor
    • output pins - external controls
    • hdc1080 - Temperature, humidity
    • ina2xx - Volts, Amps and Watts
    • pfc8583 counter, sonar distance
    • serial - pm2.5, NMEA etc
    • veml6075 - UV index
  • Arduino & ESP32 programming
    • Set up Arduino IDE
    • Set up Arduino CLI
    • Arduino OTA updates
    • Using external serial adapters
    • Add fonts to LCDGFX
  • xymon
    • Disk I/O
    • SNMP
    • Varnish cache
    • VMware Balloon
  • Network & web server config
    • Basic Ubuntu config
    • Intro to networking
    • PHP and CGI app in Nginx
    • https redirection in Nginx
  • Model building
    • miniThrottle introduction
    • miniThrottle build notes
    • miniThrottle work in progress
    • Precompiled miniThrottle
    • miniThrottle Web Interface
    • Scale Calculator

Features

MiniThrottle is a wireless (WiFi, for DCC-Ex or WiThrottle) or serially connected (DCC-Ex) model train throttle.

• Open source software free for hobbyist use, but a financial contribution would be appreciated if used commercially.
• esp32 based It uses a common, but powerful micro controller as its core, different modules are available which minimise the project component count.
• Multi-protocol Two protocols are supported:
  • WiThrottle (WiFi Only)
  • DCC-Ex (WiFi or serial)
• Multi-optioned feedback These include:
  • different displays
  • LED status indicators
  • 3v voltmeter for speedometer and brake pressure
• Multi-optioned input These include:
  • different keypads
  • Rotary Encoder
  • Forward/reverse switch
  • Throttle potentiometer
• Serial console allows wifi network affinity and other settings to be changed without having to re-program the micro controller
• Multiple WiFi networks allowing the throttle to be portable and used on multiple layouts. Alternatively a direct serial connection to DCC-Ex may be used, which bypasses WiFi connectivity.
• Menu driven user interface makes it easy for visitors or occasional users to use

The project is in a sense "incomplete". Many final design decisions are left to the constructor. This allows the builder for example to:

• Customise a throttle to suit a particular user, eg someone with a disability.
• Build handheld and panel mount throttles with different features, but which share the same "operating manual".

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.

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.

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:

• Graphical Interface (https://conferre.cf/HydraFerret/gui.php)
• Command Line Interface (https://conferre.cf/HydraFerret/cli.php)

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.

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:

• Board: ESP32 Arduino --> LOLIN 32
• Upload speed: 921600
• Flash frequency: 80 MHz
• Partition Scheme: Minimal SPIFFS (large APPS with OTA)
• Core Debug Level: None

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

Hardware Selection

Bill of Materials

Processor

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.

Display

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:

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/200^th of the reading distance, and 1/150^th of the distance may be more readable.

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.

Keypad

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.

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.

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

• Track Power
• bidirectional / trainset / shunting mode indicator
• F-button +10 indicator
• F-button +20 indicator

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:

Diagnostics

• config Shows the general configuration of the MiniThrottle device
• export Exports the commands required to duplicate this MiniThrottle's configuration. This is useful when usng more than one MiniThrottle on a system or to simply create a backup.
• locos or turnouts Lists locos or turnouts known to the device
• nvs Show the contents of "Non Volatile Storage" - these are the device's settings that are retained after power off or reset.
• pins Shows the esp32 pin assignments - each pin should have at most one assigned function. Check there are no duplicate pins. Unassigned pins are OK.
• showkeypad Shows which keys are being pressed, useful for checking keypad configuration. "noshowkeypad" to stop.
• showpackets Shows the data sent to and from the miniThrottle and the control station. "noshowpackets" to stop.
• sendcmd Sends a command to the control station. You need to understand the protocol used by the control station before attempting this. eg on DCC-Ex to power on track: sendcmd <1>

Display set up

• font Get or set display font to use
• rotatedisplay get or set the display orientation
• cpuspeed Set the processor speed, slower speeds may have slower screen update/refresh times but consume a little less power.

Wireless set up

• name Sets the name of the throttle, when using WiThrottle this can aid in distinguishing various throttle units.
• protocol designates which protocol to defer to if the command station sends no initial identifing information within the first few seconds of connection.
• server In the event mDNS query does not identify your control station, the server command can direct the throttle to a control station IP address/Name and port number. These get polled sequentially until one connects. By specifying multiple ser entries a MiniThrottle can easily move between layouts.
• wifi Used to specify WiFi networks you want to connect your MiniThrottle to. It will require the WiFi SSID and password. By specifying multiple networks a MiniThrottle can move between different networks. At least one wWiFi network must be specified.
• wifiscan Normally MiniThrottle will poll networks in turn and connect to the first discovered network. By enabling wifiscan, network signal strength is scanned an the MiniThrottle is attached to the strongest signal. However, this mode can sometimes lead to unexpected disconnection and reconnection.

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.

• add Adds locomotives, turnouts or routes to the MiniThrottle.
• del Deletes locomotives, turnouts or routes from the MiniThrottle.

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

Locomotives
Turnouts
Routes
Track Power
CV Programming
Configuration

Locomotives

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

Turnouts

This menu is used to select a turnout by name and set it either Closed or Thrown.

Routes

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

Configuration

Bidirectional Mode
CPU Speed
Font
Info
Protocol
Restart
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:

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.