flash62au / WiTcontroller

WiTthrottle Protocol based WiFi model train controller for JMRI, DCC-EX etc.
https://dcc-ex.com/ex-toolbox/index.html
Apache License 2.0
15 stars 11 forks source link

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 a video of it in use here.

Discussion on Discord.

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 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

Building

Required Components

Optional Components

Pinouts

Standard Configuration Pinouts Assembly diagram

Pinouts for Optional Additional Buttons Assembly diagram - Optional Additional Buttons

Pinouts for Optional 4x4 keypad and Additional Buttons Assembly diagram - 4x4 keypad and Optional Additional Buttons

Pinouts for Optional Battery Monitor and Additional Buttons Assembly diagram - Optional Battery Monitor and Additional Buttons

Default Pins for the keypads

3x4 Keypad - Left to Right

4x4 keypad - Left to Right

Notes:

Case

3D printer case 1

3D printed case 2

Notes:

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
      1. 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/)
    • 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
        1. 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/WiTcontroller 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/WiTcontroller
      • 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.
        1. Load the needed libraries to your PC.
          These MUST BE loaded from the Library Manager in the Arduino IDE.
    • U8g2lib.h - Search for "U8g2". Install version 2.34.22
    • AiEsp32RotaryEncoder.h - search for "Ai Esp32 Rotary Encoder". Install Version 1.6
    • Keypad.h - Search for "Keypad" by Mark Stanley. Install version 3.1.1
    • WiThrottleProtocol.h - Search for "WiThrottleProtocol" (not "WiThrottle"). Install version 1.1.14 or later if available.

      Note:
      DO NOT download these libraries directly. Use the Library Manager.
      DO NOT put them in the WiTcontroller folder.

      1. 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

      Note:
      DO NOT download these libraries directly. Use the Boards Manager.
      DO NOT put them in the WiTcontroller folder.

      1. Copy the two example config files.
        You will need to use a File Manger type of app on the PC to do this.
    • Copy config_network_example.h to a new file to config_network.h.
    • Copy config_buttons_example.h to a new file config_buttons.h.

      Note:
      these files are not included in the download, so that you can personalise your configuration without fear that those configurations will be overridden if you update (download again) the WiTcontoller code.

  1. Open the Arduino IDE and THEN find and open the WiTcontoller.ino file.

    Note:
    If you open the file from the IDE, rather then opening it from a File Manager, will automatically open all the files in the WiTcontroller folder in the IDE.

    Whereas, if you open it from a File manger app (by double clicking on it) only the file you selected will open.

  2. Edit your personal config_network.h file.

    • Edit it to include the network SSIDs you want to use. (Not essential, but entering passwords via the encoder is tedious.)
  3. Edit your personal config_buttons.h file.

    • 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
  4. 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 -->

Notes:


Using WiTController

Currently functioning:

ToDo:

Command menu:

Pressing the Encoder button while the ESP32 is in Deep Sleep will revive it.


Screens

WiFI/SSID Connection Screens

Start-up - browsing for SSIDs
Start-up - browsing for SSIDs

SSID (WiFi networks) list
SSID list

Trying to to connect to SSID
Trying to to connect to SSID

WiThrottle Server Connection Screens

WiThrottle Server List
WiThrottle Server List

Throttle Screen

Throttle Screen with no loco acquired
Throttle Screen with no loco acquired

Throttle Screen - with locos selected on throttle 1 and throttle 2
Throttle Screen

TT LLLL LLLL LLLL               BBBBB
TT ----------------------------------
f f f f f f f f f f f f f f f f f f f
              SSSSS  DDDD
              SSSSS  DDDD
              SSSSS            
M             SSSSS              llll
P  h                          d sss d
-------------------------------------
mmmmmmmmm

* Menu

Menu

Direct Commands List

Direct Commands List


Default number key assignments (0-9) (outside the menu)

Allowed assignments for the 0-9 keys:

Note: you need to edit config_buttons.h to alter these assignments (copy config_buttons_example.h)


instructions for optional use of a potentiometer (pot) instead of the encoder for the throttle

config_buttons.h can include the following optional defines:


Instructions for optional use of a voltage divider to show the battery charge level

See diagram above for how to wire in the volage divider. 47k resistors are used, but this can be varied as long as the output to the pin is limited to below 3.3v. See additional information related to the Pangodream Library that WiTcontroller uses here... https://www.pangodream.es/tag/18650-ion-li

The diagram has the voltage divider spliced into battery leads, but you can solder the positive in to the back of the battery connector (on the ESP32) if you prefer. The ground can be taken from any ground pin.

To enable the battery monitor, set the following to true. The default is false.

#define USE_BATTERY_TEST true

To set which pin to use. The default is 34. In theory 34, 35, 36, or 39 should be able to be used, but only 34 and 36 have been tested. (36 is marked 'VP' on the board. 39 is marked 'VN' on the board.)

#define BATTERY_TEST_PIN 34

If the battery does not show 100% when plugged into the charger, you may need to adjust this value. The default is 1.7.

#define BATTERY_CONVERSION_FACTOR 1.7

To show the calculated percentage, set the following to true The default is false.

#define USE_BATTERY_PERCENT_AS_WELL_AS_ICON true

To force the HandCab to go to sleep at a specific level, set this value. (e.g. to 3 or 5.) A value of less than zero (e.g. -1) will disable the feature. By default it is disabled (-1).

#define USE_BATTERY_SLEEP_AT_PERCENT 3

The display of the battery can be temporarily toggled by setting a key or button to SHOW_HIDE_BATTERY. The display will cycle between none, icon only and icon plus percent value. Note that USE_BATTERY_TEST must be set to true for this to have any effect.

Note: 
I recommend adding a physical power switch to disconnect the battery as this feature will, slowly, continually drain the battery, even when not being used.

Instructions for German Translations Anleitung für deutsche Übersetzungen

The file Deutsche Übersetzungen.txt contains German translations (by Google Translate). Add the contents of this file (cut and paste) into your config_buttons.h to see menus and messages in German.

Die Datei Deutsche Übersetzungen.txt enthält deutsche Übersetzungen (von Google Translate). Fügen Sie den Inhalt dieser Datei (Ausschneiden und Einfügen) in Ihre config_buttons.h ein, um Menüs und Meldungen auf Deutsch anzuzeigen.

I would appreciate any assistance to improve these translations. If you are interested, please contact me directly for instructions.

Ich würde mich über jede Hilfe zur Verbesserung dieser Übersetzungen freuen. Bei Interesse kontaktieren Sie mich bitte direkt für eine Anleitung.



Change Log

V1.72

V1.71

V1.70

V1.69

V1.68

V1.67

V1.66

V1.65

V1.63 - v1.64

V1.62

V1.61

V1.60

V1.59

V1.58

V1.56 / 1.57

V1.55

V1.54

V1.53

V1.52

V1.51

V1.50

V1.49

V1.48

V1.47

V1.46

V1.45

V1.44

V1.43

V1.43

V1.42

V1.41

V1.40

V1.38 & V1.39

V1.36 & V1.37

V1.35

V1.34

V1.33

V1.32

v1.31

prior