WiTcontroller

A WiTcontroller is a simple DIY, handheld controller that talks to a WiThrottle Server (JMRI, DCC-EX EX-CommandStation, Digitrax LnWi and many others) using the WiThrottle protocol to control DCC model trains.

See full change log/ version history

---

Why WiTcontroller?

<img src="images/petegsx_version.png" width="150" style="float:right;"></img>

There are a number of excellent DIY DCC controllers available, but most require a lot of components and a lot of soldering. I wanted to create the simplest possible controller so that it would be as easy (as possible) to make one.

In its basic form, the WiTcontroller uses only four components plus a battery. You can even put it together without soldering, though I don't recommend that for long term use.

While the basic form is simple, the design is flexible and you can add several additional components if you wish.

See a video of it in use here.
and another... (from GingeAngles) and another... (from Sumner)

The name

WiTcontroller is a contraction of 'WiThrottle Controller' as it uses the WiThrottle Protocol for communications with the server. I pronounce it as 'Wit Controller', but you can pronounce it however you like.😊

[!NOTE]

• 'WiThrottle' is a trademark owned by Brett Hoffman. It is also an iOS app developed by Brett Hoffman.
• The 'WiThrottle protocol' is a communications protocol developed by Brett Hoffman. It is used by WiTcontroller, JMRI, Engine Driver, the WiThrottle app plus a number of other apps and DCC Command Stations. References in this document to a 'WiThrottle Server', refer to any server that can communicate using the 'WiThrottle protocol'.

---

Index / Contents

• Prerequisites
• Building
• Loading the Code
• Using WiTcontroller
• Allowed Actions
• Options and Extras
• Contact Me <br/> <br/>
• Modifying the code
• Change Log

<br/> <hr style="border: none; height: 4px; background-color: #007bff; border-radius: 2px;">

Prerequisites

1. Some basic soldering skills.

   The components will work if just plugged together using jumpers, but they take a lot of space that way, so soldering them together is advised to make it more hand held.

2. Loading the code (sketch) requires downloading of one of the IDEs, this sketch, the libraries, etc. so some experience with Arduinos is helpful, but not critical.

3. A WiThrottle Server to connect to. WiTcontroller will work with any WiThrottle Server. e.g.

   • JMRI
   • DCC-EX EX-CommandStation
   • MRC WiFi
   • Digitrax LnWi
   • NCE WiFiTrax
   • and others

   Note that there seems to be an issue with the YaMoRC Command Station that I am still working on. See the notes for the DEFAULT_HEARTBEAT_PERIOD define below.

<br/> <hr style="border: none; height: 4px; background-color: #007bff; border-radius: 2px;">

Building

Required Components

1. WeMos Lite LOLIN32 (ESP32 Arduino with LiPo charger) (Example)

   Note: Any ESP32 will work but the pinouts may need to be adjusted, and a separate LiPo charger may be required

[!CAUTION] I have reports of some of the versions of this board with the USB-C connectors having problems with the WiFi. Some are clearly fine, but others are not. I am still investigating this, but I would recommend avoiding the USB-C version for now.

2. 3x4 Keypad (Example)

   Notes:

   • Alternately a 4x4 keypad can also be used (see optional components below)
   • Different keypad manufacturers may arrange the pins on the base of the keypad differently.*** See notes in the Default Pins for the keypads section below.

3. KY-040 Rotary Encoder Module (Example)

   Notes:

   The EC11 rotary encoder will also work, but requires a small configuration change in config_buttons.h (see below)

4. OLED Display 0.96" 128x64 I2C IIC SSD1306 (Example)

   Notes:

   • The code for the one of the common 1.3" displays is also included (see below).
   • Some OLED displays up to 2.4 inch will also work (see below)

5. Polymer Lithium Ion Battery LiPo 400mAh (or larger) 3.7V 502535 JST Connector. (500mAh Example)

   Notes:

   • Any capacity battery will work. A 400mAh will give about 6 hours of run time.*

[!WARNING] I have found that some batteries come with the positive and negative leads the other way around to the terminals on the ESP32. <br/> Check they are correct before plugging it in. <br/> The polarity of the battery is easy to swap, by getting a knife blade under the small tabs on the plastic connector and pulling each male socket out. Take extreme care. DO NOT SHORT THE TERMINALS.

6. A Case to put it in. Links to a few different designs are below, but any box will do. My case was 3d printed for me (see below).

7. A Knob (Example)

8. Wire - If you plan to solder the connections, which is the recommended approach, then stranded, coloured wire is advisable. (Example)

Optional Components

9. Optional: A power switch. Push button or toggle. <br/> The battery in WiTcontroller will last a week or two in deep sleep, but you may wish to add a power switch on the positive feed of the battery if you expect to leave it unused for long periods.

10. Optional: You can use a 4x4 keypad instead of the 3x4 keypad. <br/> Note: You will need to make a small configuration change in config_buttons.h for this to work correctly.

11. Optional: Up to eleven (11) additional push buttons can be added directly to the ESP32, each with their own independent commands. (Example)

12. Optional: A 1.3" or 2.4" OLED Display (128x64) can be used instead of the 0.96" OLED Display 128x64 (Example) Note: You will need to make a minor change in the config file for this to work correctly.

13. Optional: It is possible to use a Potentiometer instead of the Rotary Encoder for throttle control. The code supports it if you make the appropriate configuration changes in config_buttons.h. However this has had only limited testing. <br/> This is documented to some degree in config_buttons_example.h if you wish to try it.

Pinouts

Standard Configuration Pinouts <br/> This is the simplest form of the WiTcontroller

Pinouts for Optional Additional Buttons

Pinouts for Optional Additional Buttons - With Pullups

Pinouts for Optional 4x4 keypad and Additional Buttons - without pullup resistors

Pinouts for Optional Battery Monitor and Additional Buttons

[!WARNING] Different keypad manufacturers may arrange the pins on the base of the keypad differently to the examples above. <br/> See notes in the Default Pins for the keypads section below.

---

Default Pins

Default ESP32 and WiTcontroller pins

<details> <summary>Click to expand to see a table of the default pinouts</summary>

         3x4    4x4    OLED Encoder  Additional   Battery
    Pin Keypad Keypad                  Buttons     Test
     0    C1     C1                             
N/A  1                                       
     2    C2     C2                             
N/A  3                                     
     4    C0     C0                             
     5                                  AB0     
N/A  6                                      
N/A  7                                      
N/A  8                                      
N/A  9                                      
N/A 10                                       
N/A 11                                       
    12                        DT               
    13                        SW               
    14                        CLK               
    15