EleksTubeHAX - An aftermarket custom firmware for the EleksTube IPS clock
Buy your own clock here: EleksTube IPS Clock
Reddit discussion on the hack is here.
Original documentation and software from EleksMaker.
How to build this firmware
Unfortunately, it's not simple plug-and-play. You need to do some things. These instructions assume you already know how to use the Arduino IDE, and just need to know WHAT to do.
Download this code
You're either reading this file after downloading it already, or you're reading it on github. I'll assume you can figure out how to get the code from github and put it somewhere on your local machine. This is your preference.
Configure your WiFi network
In the source code directory (where ever you just installed it), copy
wifi_creds.h and edit it for your WiFi SSID and Password.
wifi_creds.h is in
.gitignore, so you can safely put credentials in that file and still submit pull requests, push code, whatever. git will never store your credentials in a repository.
Setup Arduino IDE
Development was done on Arduino 1.8.13. It might work on earlier or later versions, I don't know.
Windows Only: Install the USB Serial Port Device Driver (??)
I'm not a Windows user, but the EleksTube instructions have you installing a driver to get the serial port to work. So I assume that's necessary. It seemed to work out of the box on my Ubuntu 16.04 machine.
Install ESP32 board support from Espressif
File -> Preferences, add
https://dl.espressif.com/dl/package_esp32_index.json to your Board Manager URLs. (Comma separated if there's already something there.)
Tools -> Board -> Board Manager, add the
esp32 boards by
Espressif Systems. Development was done on v1.0.6.
Tools -> Board -> ESP32 Arduino -> ESP32 Dev Module
The default configs in the Tools menu should be fine. The important ones are:
- Flash Size: 4MB
- Partition Scheme: Any that includes at least 1MB for SPIFFS. I use the "Default 4MB: 1.2MB App, 1.5MB SPIFFS" one.
- Port: Set it to whatever serial port your clock shows up as when plugged in.
All these libraries are in Library Manager. Several libraries have very similar names, so make sure you select the correct one based on the author. The listed "developed on" versions are just the versions I had installed while developing this code. Newer (or possibly older) versions should be fine too.
Sketch -> Include Library -> Library Manager
NTPClientby Fabrice Weinberg (developed on v3.2.0)
Adafruit NeoPixelby Adafruit (developed on v1.8.0)
DS1307RTCby Michael Margolis (developed on v1.4.1)
TFT_eSPIby Bodmer (developed on v2.3.61)
Timeby Michael Margolis (developed on v1.6.0)
IMPORTANT You have to do this after every time you install or update the
TFT_eSPI library! IMPORTANT
The full documentation for this is in the
TFT_eSPI library, but tl,dr:
- Comment out all
#includelines. (The only one that comes from install is
- Add a
#includeline pointing to
User-Setup.hin this code.
- Obviously, update the path to point to where ever you keep your code. Mac and Windows paths will look very different.
Install SPIFFS uploader
The code is here, and instructions to install it are here.
tl,dr: Download and unzip this file into your
Arduino/tools/ directory. There might not be a
tools/ subdirectory yet, but if you see
Arduino/libraries/ that's the right place.
After installing the ESP32 support, all the libraries, and the SPIFFS uploader, restart Arduino to make sure it knows its all there.
Upload New Firmware
Make sure you configured everything:
- Put your wifi credentials in
User_Setup_Select.hin the TFT_eSPI library to our
Connect the clock to your computer with USB. You'll see a new serial port pop up. Make sure that's the serial port selected in Tools.
Compile and Upload the Code
Compile (Ctrl-R) and Upload (Ctrl-U) the code. At this point, it should upload cleanly and successfully. You'll see the clock boot up and connect to WiFi. But it doesn't have any bitmaps to display on the screen yet.
The repository comes with a set of BMP files, nixie tubes from the original firmware, in the
data/ directory. See below if you want to make your own.
Tools -> ESP32 Sketch Data Upload, will upload the files to the SPIFFS filesystem on the micro. They'll stay there, even if you re-upload the firmware multiple times.
Custom Bitmaps (Optional)
If you want to change these:
- Create your own BMP files. Resolution must be 135x240 pixels, 24bit RGB.
- Name them
9.bmpand put them in the
Then do the "Tools -> ESP32 Sketch Data Upload" dance again.
Check in original-firmware/ for a direct dump of the firmware as I received my clock, and instructions for how to restore it to the clock. This is useful if you're hacking around and get some non-working code, and just want to restore it to original.
Unpacking BMPs from original firmware
Download and unpack the original software (link above). It contains a directory called
IPSimages/ which contains several pre-made SPIFFS images full of the BMPs available in the original software. You can see what they all look like in the
gallery/ directory, same numbers.
To unpack one of these SPIFFS images into the original BMPs:
- Make a destination directory, eg:
mkspiffs -u unpacked/ [image].bin
- This assumes you've already installed ESP32 support in Arduino.
mkspiffscomes with the ESP32 tools. On my Linux system, it's in
- If you're on Windows, the IPS software also comes with
mkspiffs.exewhich I assume works the same way, but I haven't confirmed.
- This assumes you've already installed ESP32 support in Arduino.
This puts 12 files in
9.bmpwhich are 135x240px 24 bit BMPs for the 10 digits
date.bmpanother couple BMPs, but I'm not sure where they're ever used. We won't need these in our firmware, so they can be deleted.
- Microcontroller: ESP32-WROOM-32D
- Displays: TFT 1.14" 135x240 (includes pinout of ribbon connector)
- ST7789 controller Datasheet
- RGB LED: SK6812 side emmitting
- NeoPixel/WS2812 compatible.
- Talking to displays: TFT_eSPI
- Real Time Clock: DS3231 RTC
- NeoPixel library for RGB LEDs (link coming)
My (SmittyHalibut) notes from reverse engineering the board
The card edge connector has 13 connection points on each side, but both sides are tied together, so there are only 13 unique pins.
The socket on the board is oriented so that Pin 1 is on the RIGHT SIDE (look for the little arrow on the top of the socket.) So the documentation below is RIGHT TO LEFT.
- WS2812 In
- WS2812 Out
- TFT pin 5, SDA, ESP32 pin 37, IO23, VSPID
- TFT pin 6, SCL, ESP32 pin 30, IO18, VSPICLK
- TFT pin 4, RS (Register Select, or DC Data Command), ESP32 pin 10, IO25
- TFT pin 3, RESET (active low), ESP32 pin 11, IO26
- TFT pin 8, Chip Select, driven by 74HC595
- WS2812, GND (Tied to 13)
- TFT pin 1 and 7, Vdd and LEDA (Tied to 12)
- TFT pin 2, GND
- Tied to system ground through a MOSFET, controlled by ESP32 pin 12, IO27, so the displays can be completely turned off.
- (If I (SmittyHalibut) were doing this, I'd have used a P channel MOSFET and controlled LEDA, which would allow dimming as well as completely shutting it off. Oh well.)
- TFT pin 1 and 7, Vdd and LEDA (Tied to 10)
- WS2812, GND (Tied to 8)
Chip Select Shift Register
There's a 74HC595 (datasheet) that drives the 6 SPI Chip Select lines on the displays. Chip Select lines are Active Low, so write 1s to the displays you do NOT want to update, a 0 to the display you want to update.
Q0 is the most recent bit written to the shift register, Q7 is the oldest bit written.
- Q0: Hour Tens
- Q1: Hour Ones
- Q2: Minute Tens
- Q3: Minute Ones
- Q4: Seconds Tens
- Q5: Seconds Ones
- Q6 and Q7: Unused, not connected.
- Ds (Data In): ESP32 pin 13, IO14, GPIO14
- /OE (Output Enable): Strapped to Ground, always enabled.
- STcp (Storage Register Clock Input): ESP32 pin 28, IO17, GPIO17
- SHcp (Shift Register Clock Input): ESP32 pin 27, IO16, GPIO16
WS2812(?) RGB LEDs
They only require a single GPIO pin to drive all 6 LEDs. They are driven in reverse order, right to left. The first LED is Seconds Ones, the sixth LED is Hours Tens.
- ESP32 pin 14, IO12
All 4 buttons are externally pulled up (an actual 10k resistor!) and shorted to ground by the button.
<<<: ESP32 pin 9, IO33
MODE: ESP32 pin 8, IO32
>>>: ESP pin 7, IO35
POWER: ESP pin 6, IO34
The DS3231 (datasheet) is an I2C device, and a very common one at that. Lots of good documentation and libraries already.
- SCL: ESP32 pin 36, IO22
- SDA: ESP32 pin 33, IO21
Mark Smith, aka Smitty @SmittyHalibut on GitHub, Twitter, and YouTube.