search

frankcohen / EleksTubeIPSHack

Hacking the Elekstube IPS ESP32 TFT based clock
GNU General Public License v3.0
69 stars 22 forks source link

readme

ElekstubeIPSHack - Hacking the Elekstube IPS ESP32 TFT based clock

EleksTube IPS is an ESP32-based digital clock. It appears to be the first in a wave of new 32-bit network-enabled multiple display products.

Photo of the EleksTube IPS sitting on a desktop displaying Nixie Tube images

EleksMaker designed it to appear to have a Nixie Tube display. Of course, it's all an ingenious fake! An ESP32 processor drives 6 TFT LCD displays. USB C connectors provide power and communication to a FTDI microcontroller programmer using a pre-programmed bootloader. The environment is familiar to users of Arduino microcontroller boards, C/C++ languages, Arduino IDE, and the ESP32 processor.

The board features 3 push buttons for set-up configuration, a power button, a real-time clock with battery backup, a power control chip to dim the displays, and 6 screens. The screens are IPS 1.14 Inch 8PIN Spi Hd Tft Lcd-screen with ST7789 driver IC. They display 135 by 240 pixels and are supported by the TFT_eSPI library.

All of this feels like an Arduino playground. I love it right out of the box! EleksTube IPS comes pre-programmed with its own firmware. At the time of writing this EleksMaker had not published the source-code to their firmware. The firmware implements its own protocol for a Windows-based application to upload new images for the clock function. Check here for details.

I'd also like to build some new experiences with it:

I started a discussion Hacking the EleksTube IPS Clock - anyone tried it? on Reddit. @SmittyHalibut, @RedNax67, and others worked to build an open-source firmware. @SmittyHalibut's firmware is here. It uses the ESP32 SPIFFS filesystem to store images. And it implements class libraries for buttons, backlights, RTC, and displays.

Using EleksHack Alternative Firmware

This repository is an alternative firmware for the clock. Compile the firmware from source code using the instructions below, or upload the compiled firmware image (from /bin in this repository) to your clock. The clock has 2 USB C ports, plug a cable between your computer and the clock. Use Arduino IDE to compile and upload the /EleksHack/ElecksHack.ino sketch from the source code. Or follow the next section to upload the pre-built firmware.

Uploading the pre-compiled binary

As an easy alternative to compiling the source code, the /bin directory has an Esptool created binary file.

We recommend you make a backup of your clock's original firmware before taking any of these steps. Use this command:

python esptool.py -b 115200 --port /dev/cu.usbserial-141210 read_flash 0x00000 0x400000 flash_4M.bin

Replace the USB port above with your own. On my MacOS 11.3.1 and Arduino IDE 1.8.13 puts esptool.py at /Users/frankcohen/Documents/Arduino/hardware/espressif/esp32/tools/esptool.py. I change to that directory, then run the above command from a Terminal window. It appears as:

esptool.py v2.8
Serial port /dev/cu.usbserial-141210
Connecting....
Detecting chip type... ESP32
Chip is ESP32D0WDQ5 (revision 1)
Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
Crystal is 40MHz
MAC: a4:e5:7c:47:20:dc
Uploading stub...
Running stub...
Stub running...
4194304 (100 %)
4194304 (100 %)
Read 4194304 bytes at 0x0 in 383.0 seconds (87.6 kbit/s)...
Hard resetting via RTS pin...
frankcohen@FCohenMac2020 tools %

Esptool.py creates a 4 Mbyte binary backup file of your clock's existing firmware.

Then, upload the binary from this repository /EleksHack/bin/ to the clock using this command:

python esptool.py -b 115200 --port /dev/cu.usbserial-141210 write_flash --flash_freq 80m 0x000000 elekstube_backup_4M_20210628.bin

Replace the USB port above with your own.

Accessing The Menu

Upon start-up the clock is a Wifi access point with the SSID of EleksHack and the password thankyou. Connect to the access point from your mobile or laptop device. Point your browser to 192.168.1.1 to view the main menu.

The clock has 2 shows: Play Clock, Play Images. The clock show is the normal EleksTube IPS clock display. The image show displays a random JPG formatted image on a random display (of the 6 displays).

Play Clock

Requires the digits of the clock to be stored in BMP format. For example, /1.bmp is the image file for the number 1. Use the Menu command Manage Media and the Upload function to store a BMP formatted file to the internal (SPIFFS) file system. Manage Media also shows the files in the file system, and the delete link removes the file. Nixie tube looking BMP files are in the /EleksHack/data directory of the source repository.

EleksTube IPS ships with SPIFFS formatted using the old and deprecated SPIFFS library. The alternative firmware uses the replacement for SPIFFS library... called LittleFS. In the Manage Media page use the Format SPIFFs File System before uploading images.

By default the clock runs in the 'Play Clock' show. The firmware will display the value stored in the Real Time Clock chip. If you do not see the clock images on the displays you will need to upload the image files to the clock. Use the Manage Media command in the main menu (in your browser). Upload the images from the /EleksHack/data directory.

To get the time from a Network Time Protocol (NTP) server on the Internet, create a Wifi connection from the clock to your nearby Wifi access point. Click Connect To Wifi from the menu. Your browser shows a scan of available Wifi networks. Click on one, enter a password, and connect. Once connected the NTP server time updates the clock time and stores the time value in the Real Time Clock chip (RTC).

NOTE: This sketch uses self-signed certificates to operate using HTTPS protocol. A self-signed certificate is a security certificate that is not signed by a certificate authority. This sketch makes its own certificate each time it starts. These certificates are easy to make and do not cost money. However, they do not provide all of the security properties that certificates signed by a CA aim to provide. For example, the Connect To Wifi page transmits passwords. It is likely that someone with light security skills could crack the certificate and learn your passwords. I recommend you use a Wifi station with no password. Or, do not use this control. Also, most browsers will ask you to override a security alert to use the self-signed certificate.

Play Images

Play Images is something I personally wanted. I use it to randomly show pictures of my children. Both my children are in love and life is good! Click Play Images from the main menu, then click Play. It picks a JPG image from the file system approximately every 2 seconds.

Photobooth

Captures a still image from a video stream from your laptop, tablet, or mobile phone camera. Slices into 6 JPEG images. Uploads the images to the EleksTube IPS SPIFFS. Displays the images on the 6 displays.

Photobooth showing captured image sliced across the 6 displays

Photobooth uses your laptop, tablet, or mobile phone's camera to capture an image, slice it into 6 smaller images, then display the images on the EleksTube IPS. It uses the WebRTC API standard and should operate on all Web browsers. I found instructions here.

Watch a 1 minute video to see Photobooth in action

For Photobooth you want the bin/elekstube_backup_4M_20210628.bin or later pre-built binary archive.

How to build this firmware

Unfortunately building this firmware from the source code is not as easy as: Arduino IDE 1.8.13 on MacOS 11.3.1. Choose Tools -> Board -> ESP Arduino (in sketchbook) -> ESP Dev Module. Set Tools -> Upload speed to 115200. There are many dependencies on external libraries:

Download the source code

Use the Code pop-up menu in Github and select the Download Zip command. Extract the source code from the Zip file.

Setup Arduino IDE

I use Arduino IDE 1.8.13. Please let me know if it does not work on versions before or later.

Windows device driver

Windows users should follow Arduino IDE instructions to install device drivers to use the USB ports to communicate with the clock.

Install ESP32 board support from Espressif

Follow instructions to add ESP32 support to Arduino IDE at: https://github.com/espressif/arduino-esp32/blob/master/docs/arduino-ide/mac.md

Software drivers and utilities for ESP32 are at: https://github.com/espressif/arduino-esp32 https://github.com/nodemcu/nodemcu-firmware/tree/dev-esp32

On MacOS 11.3.1 I needed to patch esptool.py following https://github.com/espressif/arduino-esp32/issues/4408 and changing the +x perms too

In Arduino IDE use ESP32 Dev Board as Board selection. The default configs in the Tools menu should be fine. The important ones are:

Install Libraries

All these libraries are in Library Manager, except for the Jpeg decoder library that must be downloaded in Zip form and installed using Sketch -> Include Library -> Install from Zip in Arduino IDE. 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

And download the zip and install in Arduino IDE using Sketch -> Include Library -> Add ZIP Library:

Configure the TFT_eSPI library

IMPORTANT You have to do this after every time you install or update the TFT_eSPI library!

The full documentation for this is in the TFT_eSPI library, but tl,dr:

Restart Arduino

After installing the ESP32 support, all the libraries, restart Arduino IDE to make sure it knows everything is present.

Upload New Firmware

Use the Arduino IDE Upload command to compile and upload the firmware to your clock. 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 messages on the 6 displays on the clock. The clock doesn't have any bitmaps to display on the screen yet.

Debug Logging to the Serial Monitor

Use Arduino IDE Serial Monitor to view debugging details as the clock operates. For example, the alternative firmware prints the connected Wifi addresses to the serial monitor when the station mode connects.

Upload Bitmaps

The repository comes with a set of BMP files, nixie tubes from the original firmware, in the /EleksHack/data directory. Connect to the clock's Wifi access point, use the main menu, Manage Media command, and upload the bitmaps.

Custom Bitmaps (Optional)

If you want to change these:

Then use the Manage Media command to upload.

Benefits for Arduino Developers

For Arduino developers, consider the Photobooth software is demonstration code for you to do these in your own projects:

Documentation

Hardware

Libraries

Hardware

@SmittyHalibut notes from reverse engineering the board

Display boards

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.

  1. WS2812 In
  2. WS2812 Out
  3. TFT pin 5, SDA, ESP32 pin 37, IO23, VSPID
  4. TFT pin 6, SCL, ESP32 pin 30, IO18, VSPICLK
  5. TFT pin 4, RS (Register Select, or DC Data Command), ESP32 pin 10, IO25
  6. TFT pin 3, RESET (active low), ESP32 pin 11, IO26
  7. TFT pin 8, Chip Select, driven by 74HC595
  8. WS2812, GND (Tied to 13)
  9. N/C
  10. TFT pin 1 and 7, Vdd and LEDA (Tied to 12)
  11. 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.)
  12. TFT pin 1 and 7, Vdd and LEDA (Tied to 10)
  13. 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.

Outputs:

Inputs:

WS2812, Neopixel (?) 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.

Buttons

All 4 buttons are externally pulled up (an actual 10k resistor!) and shorted to ground by the button.

RTC DS3231

The DS3231 (datasheet) is an I2C device, and a very common one at that. Lots of good documentation and libraries already.

Next steps

Implement HTTPS to protect Wifi connection passwords https://esp32.com/viewtopic.php?t=19452

Let the ESP32 select Wifi connections based on signal strength and availability https://diyprojects.io/esp32-how-to-connect-local-wifi-network-arduino-code/#.YKxQz5NKiog

License

This work is distributed for free under a GPL version 3 open-source license.

Contributers

@FrankCohen, @SmittyHalibut, @RedNax67

Please feel free to jump-in here. Make a contribution, make a fork, make a comment, open a bug report. The water is warm and all are welcome.