DccExController

Please note:

• For the foreseeable future I will not be maintaining this code base. <br> I would recommend switching to WiTcontroller
• I will not be providing any support for this code.
• I am no longer contactable on the DCC-EX Discord server.
• As always, you are welcome to fork the code and do with it as you wish, within the limits of the licence.

Description

A DccExController is a simple DIY, handheld controller that talks to a wThrottle Server (JMRI, DCC++EX and many others) using the Native DCC-EX protocol, exclusive to the EX-CommandStations, to control DC and DCC model trains.

3d Printed Case

---

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 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. An EX-CommandStation to connect to. DccExController will ONLY work with any EX-CommandStations!

---

Building

Required Components

• WeMos Lite LOLIN32 (ESP32 Arduino with LiPo charger) (Example)
• 3x4 Keypad (Example)
• Polymer Lithium Ion Battery LiPo 400mAh 3.7V 502535 JST Connector (or larger capacity) (500mAh Example)
• KY-040 Rotary Encoder Module (Example)
• OLED Display 0.96" 128x64 Blue I2C IIC SSD1306 (Example)
• Case - my one was 3d printed (see below)
• Knob (Example)
• Wire - If you plan to solder the connections,which is the recommended approach, then stranded, coloured wire is advisable. (Example)

Optional Components

• Optional: Up to 7 additional push buttons can be added, each with their own independent commands. (Example)
• Optional: A 1.3" OLED Display 128x64 can be used instead of the 0.96" OLED Display 128x64 (Example) Note: You will need to make a small configuration change for this to work correctly.
• Optional: You can use a 4x4 keypad instead of the 3x4 keypad. Note: You will need to make a small configuration change in config_buttons.h for this to work correctly.

Pinouts

Standard Configuration Pinouts

Pinouts for Optional Additional Buttons Default Pins for the keypads

3x4 Keypad - Left to Right

• C1 PIN 0
• R0 PIN 19
• C0 PIN 4
• R3 PIN 16
• C2 PIN 2
• R2 PIN 17
• R1 PIN 18

4x4 keypad - Left to Right

• C0 PIN 4
• C1 PIN 0
• C2 PIN 2
• C3 PIN 33
• R0 PIN 19
• R1 PIN 18
• R2 PIN 17
• R3 PIN 16

Notes:

• Different keypads often arrange the pins on the base of the keypad differently. So it is important make sure the pins on the keypad are correctly identified and adjusted as needed.

Case

Notes:

• My case was 3D Printed for me by peteGSX (See the Thingiverse. )

• The 3x4 keypad petGSX designed the case for came from Jaycar and is slightly narrower than the one you see in the 'deconstructed' view in the video above.

• The case requires about a dozen M2x4mm screws

• For a different take on what is possible by extending the design, have a look at: https://1fatgmc.com/RailRoad/DCC/page-5-B.html Note, this uses the WiTcontroller code, but will work equally as well with the DccExController.

Loading the code

The instructions below are for using the Arduino IDE and GitHub Desktop. Visual Studio Code (VSC) can be used instead of the Arduino IDE but no instructions are included here.

1. Download the Arduino IDE.

   • Available from https://support.arduino.cc/hc/en-us/articles/360019833020-Download-and-install-Arduino-IDE

2. Download the esp32 boards in the Arduino IDE.

   • add the esp322 support with the following instructions: (See here for detailed instructions: https://randomnerdtutorials.com/installing-the-esp32-board-in-arduino-ide-windows-instructions/)
     • In the Arduino IDE, go to File > Preferences
     • Enter the following into the 'Additional Board Manager URLs' field: https://dl.espressif.com/dl/package_esp32_index.json
   • Then Use the Boards Manager in the Arduino IDE to install the esp32 board support
     • Tools > Board > Boards Manager
     • Search for "esp32" by Expressive Systems. Install version 2.0.11

3. Download or clone this repository. (Note: if you 'clone' initially, it is easier to receive updates to the code by doing a 'fetch' subsequently. See Notes below.)

   • Clone - First Time
     • Install GitHub Desktop from https://desktop.github.com/
     • Create a free account on GitHub and authorise the app to allow it to connect top GitHub
     • Select file -> Clone Repository - or 'Clone an repository from the internet' from the welcome page then select the 'URL' tab
     • Enter https://github.com/flash62au/DccExController as the URL
     • Select a local folder to install it. The default folder for the Arduino usually looks like "...username\Documents\Arduino". (This is a good but not essential place to put it.)
     • Click Clone
     • Subsequently (Anytime after the first 'clone')
       • click Fetch Origin and any changes to the code will be bought down to you PC, but you config_buttons.h and config_network.h will not be touched.
   • Download
     • Open https://github.com/flash62au/DccExController
     • Click the green "Code" button and select download zip
     • Extract the zip file to a local folder. The default folder for the Arduino usually looks like "...username\Documents\Arduino". This is a good but not essential place to put it.

4. Load the needed libraries to your PC. <br/> These MUST BE loaded from the Library Manager in the Arduino IDE.

   • U8g2lib.h - Search for "U8g2". Install version 2.35.30 or later. <br/> (later versions should work, but go back to this 2.35.30 if you have problems.)

   • AiEsp32RotaryEncoder.h - search for "Ai Esp32 Rotary Encoder". Install Version 1.4

   • Keypad.h - Search for "Keypad" by Mark Stanley. Install version 3.1.1 or later. <br/> (later versions should work, but go back to this 3.1.1 if you have problems.)

   • dccexProtocol.h - Search for "DCCEXProtocol" Install version 0.0.6, or later if available

     Note: <br/> DO NOT download these libraries directly. Use the Library Manager. <br/> DO NOT put them in the DccExController folder.

5. These should have been automatically installed when you downloaded the esp32 boards. YOU SHOULD NOT NEED TO DO ANYTHING SPECIFIC TO GET THESE

   • WiFi.h - https://github.com/espressif/arduino-esp32/tree/master/libraries/WiFi

   • ESPmDNS.h - https://github.com/espressif/arduino-esp32/blob/master/libraries/ESPmDNS

     Notes: <br/> DO NOT download these libraries directly. Use the Boards Manager. <br/> DO NOT put them in the DccExController folder. <br/> These libraries do not appear in your list of libraries, but will be available to use regardless. (The files are actually buried away in a subfolder of the ESP32 Boards library.)

6. Copy 'config_network_example.h' to a new file to 'config_network.h'.

   • Then edit it to include the network ssids you want to use. (Not essential, but entering passwords via the encoder is tedious.)

7. Copy 'config_buttons_example.h' to a new file 'config_buttons.h'.

   • Optionally, edit this to change the mapping of the keypad buttons to specific functions.
   • Optionally, edit this to configure the additional buttons (if you have included them) to specific functions.
   • Optionally, edit this to change if you want the function buttons to display when you press #, instead of the default of showing the Key Definitions

8. Upload the sketch.

   • Select the board type as "WEMOS LOLIN32 Lite" in the Arduino IDE.
   • Connect the board via USB and select the appropriate port in the Arduino IDE.
   • Click Upload

Version Notes:

• DccExController version 0.23 or later requires DCCEXProtocol version 1.0.1 or later.
• DccExController version 0.20 or later requires DCCEXProtocol version 0.0.16 or later.
• DccExController version 0.16 or later requires DCCEXProtocol version 0.0.12 or later.
• DccExController version 0.12 or later requires DCCEXProtocol version 0.0.10 or later.
• DccExController version 0.02 or later requires DCCEXProtoco