A Bluetooth ESP32 TFT + Touch Macro Keypad)

Controlling your computer by using hotkeys and macros is a great way of speeding up your workflow. Unfortunately a device dedicated to doing that (for example Elgato's Stream Deck) will cost you about $120.

That is why I designed FreeTouchDeck. FreeTouchDeck will cost you about $20 (including shipping!) to make. It uses an ESP32 and a 3.5" touch screen. Keystrokes and macros are send via Bluetooth to your Windows, MacOS, or Linux computer.

You can customize your FreeTouchDeck by using the configurator. The configurator is a webpage that is hosted on the ESP32 itself. You can customize menus, buttons, logos and colours. You can also create your own button logos and upload them.

This is a really simple build and will take up less then an hour of your time + a few cups of coffee. I designed it so it can be build using parts that can be easily found on AliExpress and Banggood but can also be found locally if you do not want to wait a while before the postman comes.

Supplies

A 38-pin ESP32-WROOM-32 Development Board AliExpress / Amazon
An ILI9488 TFT screen with XPT2046 touch controller AliExpress / Amazon
An optional ESP32 + TFT Combiner PCB

Tools:

A soldering iron and solder.
Wire strippers (if you are not using the PCB).
Flush cutter.

Even better than buying the loose parts and have to build it, is using the ESP32 TouchDown. Which I designed and sell. It is an ESP32 with an capacitive touch screen. It has USB-C and battery management for fully wireless operation. It comes with an SD Card slot and a passive buzzer. You can buy it here.

Step 1: Learn More About FreeTouchDeck

Before you start this project it might be a good idea to watch the video I made. The video in itself isn't a how-to, but more of an introduction to what FreeTouchDeck is and what it can do for you!

Watched the video? Let's get the parts you'll need!

Step 2: Get the Parts You'll Need

If you do not already have an ESP32 and an ILI9488 TFT + Touchscreen lying around. You can find them pretty cheap on AliExpress. I used these parts:

- A 38-pin ESP32-WROOM-32D Development Board from AliExpress or Amazon*

- An ILI9488 TFT screen with XPT2046 touch controller from AliExpress or Amazon*

- An optional ESP32 + TFT Combiner PCB (Gerber file)

Not all ILI9488 TFT screens are created equally. It is important to make sure you have selected a screen with touch!

*Full disclosure: these are affiliate links

Step 3: Hardware: Connect the TFT Screen to the ESP32

The wiring may seem a bit daunting at first. But don't let all the wires scare you. It is pretty straight forward. The images above will help you when you wire your TFT + Touchscreen to your ESP32. This is also decision making time. There are few options when it comes to connecting the two together. You can use a breadboard, you can use prototyping board or you can order a PCB specifically to connect the ILI9488 + touch to the 38-pin ESP32 DevKitC. I'd like to point out that the breadboard option is only an option for testing your connections and screen. It is not very practical to have on your desk and loose connections can cause problems.

It is important to know that these screens run at 3.3V. Connecting them to 5V can cause damage!

These are the connections you need to make from the ESP32 -> ILI9488:

3.3V -> VCC

GND -> GND

GPIO15 -> CS

GPIO4 -> RESET

GPIO2 - > DC/RS

GPIO23 -> SDI(MOSI) and T_DIN

GPIO18 -> SCK and T_CLK

GPIO32 -> LED

GPIO21 -> T_CS

GPIO19 -> T_DO

GPIO27 -> T_IRQ

SDO(MISO) is not used for the TFT screen, so you are left with one unconnected pin on the TFT module. That's ok!

If you like to order a PCB designed to make it easy to connect the ESP32 to the TFT screen, you can download the gerber files here: https://github.com/DustinWatts/ESP32_TFT_Combiner

You can also order them directly from PCBWay where I had mine made:

https://www.pcbway.com/project/shareproject/ESP32_TFT_Combiner_V1.html

Step 4: Using the Web Installer to Install the Firmware. (Recommended)

Next there are two options. You can install all the software manually (Step 5 through 8). Or use the new (as per April the 18th 2022) FreeTouchDeck Web Installer. I recommend the Web Installer as it will save you time and there a less chances you will make a mistake.

For the Web Installer to work, you will need to use Chrome, Opera or Edge as your browser!

Go to https://install.freetouchdeck.com

Select the "ESP32 DevKitC" option

Click “Connect”

A pop-up window telling you that install.freetouchdeck.com wants to connect to a serial port pops up. Plug in your newly made FreetouchDeck. A new port now shows up in the list.

Select this port and click “Connect”

After it connects, click “Install FreeTouchDeck”.

A message prompts you with the version that is about to be installed and that all data will be erased before the new installation begins. This is fine, there is nothing important on our device anyway.

Click “Install”.

Note that at some point the installation might seem to “hang”. It I actually not, the percentage will not update, but the device is really being programmed. So nothing to worry about!

After some time the installation will be done. And on your FreeTouchDeck you are greeted with a calibration screen. This is the time to skip to Step 8! (Step 9 if you wish to print a case later)

Step 5: Software: Installing Arduino IDE Libraries

Installing the Arduino IDE ESP32 core.

Go to Arduino -> Preferences and click on the icon behind the input field for Additional Board Managers URLs.

Next, copy and paste the following link (without quotes) in the popup box:

"https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json"

Click OK and OK.

Next, go to Tools -> Board: -> Board Manager and search for "ESP32". Install the latest version and click "Close".

Installing the necessary libraries.

FreeTouchDeckuses a few (some might call 6 more than a few) libraries. Three of these libraries can be installed though the the Library Manager. Go to Sketch -> Include Library -> Manage Libraries and search for, and install the following libraries:

Adafruit-GFX-Library
TFT_eSPI
ArduinoJson

The other three libraries need to be downloaded manually. For each of them the process is the same so I'll describe just one of them.

Go to "https://github.com/T-vK/ESP32-BLE-Keyboard", click on "Releases" and under the latest release, click on "Assests" and "Download _libraryname_.ZIP". In the Arduino IDE, go to Sketch -> Include Library -> Add .ZIP library. You can also directly unpack the folder in the .zip in to your libraries folder (usually "Documents/Arduino/libraries."

Repeat for the following libraries:

"https://github.com/me-no-dev/ESPAsyncWebServer"
"https://github.com/me-no-dev/AsyncTCP"

If there is no release, then on the main page click "Code", and then "Download ZIP"

Step 6: TFT Screen Configuration

Before compiling and uploading the FreeTouchDeck.ino sketch, you will have to edit the user_setup.h file included with the TFT_eSPI library. This can be found in your Arduino sketchbook folder under "libraries". If you have not renamed the TFT_eSPI library folder, the file user_setup.h can be found in TFT_eSPI-master. Here you will have to uncomment the lines that apply to your hardware configuration.

To make things easier, you can find the user_setup.h file you will need for this project in the downloaded repository in the "user_setup.h Examples" folder. Copy the file "ESP32_Dev_Kit_V1_ILI9488_Resistive.h" to "/TFT_eSPI-master/". Rename the "User_Setup.h" that is already there to "User_Setup.old" (this way you keep the original in case something goes wrong). Now rename "ESP32_Dev_Kit_V1_ILI9488_Resistive.h" to "User_Setup.h". (<- CASE sensitive!) Save and close the file.

Step 7: Download FreeTouchDeck.ino and Upload to the ESP32

ESP Sketch Data Upload Tool

FreeTouchDeck uses the SPIFFS (ESP32 flash memory) to store configuration and images that are used. You'll need to upload these to the ESP32 before you upload the sketch to the ESP32. For this you'll need the ESP32 Sketch Data Upload tool. You can download this from Github: "https://github.com/me-no-dev/arduino-esp32fs-plugin". Follow the instructions on the Github to install the tool:

Download the tool archive from releases page.
In your Arduino sketchbook directory, create tools directory if it doesn't exist yet.
Unpack the tool into tools directory (the path will look like /Arduino/tools/ESP32FS/tool/esp32fs.jar).
Restart Arduino IDE.

(On MacOS create the tools directory in ~/Documents/Arduino/ and unpack the files there).

FreeTouchDeck.ino

On Github you can find the full source code for FreeTouchDeck. Go to the FreeTouchDeck Github repository and click "Code" and "Download .ZIP": https://github.com/DustinWatts/FreeTouchDeck

Extract and rename the extracted folder to "FreeTouchDeck". Open the FreeTouchDeck.ino sketch in the Arduino IDE. This will also open a few other header (.h) files. You do not need to touch (pun intended) these.

**Since version 0.9.11 the next step is no longer necessary! You can still edit this if you want but if you do not edit the config before uploading, if you start the configurator and it can't connect to an Access Point it will start one. You can then enter the configurator and edit you wifi settings in there.**

Set your WiFi Settings

Once you have the FreeTouchDeck.ino sketch open go to the folder you have the FreeTouchDeck.ino sketch in, open "/data/config/wificonfig.json". This is where you can enter you're WiFi SSID and Password so you can connect to your FreeTouchDeck to configure it

change "YOUR_WIFI_SSID" to the WiFi SSID you want FreeTouchDeck to connect to.
change "YOUR_WIFI_PASSWORD" to the Password that WiFi network uses.

Upload the data folder

Before you upload the data folder to the ESP32, you'll first have to select the right partitioning scheme.

Go to Tools -> Board and select ESP32 Dev Module.
Still under Tools, select Partition Scheme. -> "No OTA (2MB APP/ 2MB SPIFFS)".
Plug in the ESP32.
Click on Tools and select "ESP Sketch Data Upload".

Tip!: If the data upload fails, chances are you have the serial monitor open. If this happens, close the serial monitor and try again.

Upload the sketch to the ESP32

After the data folder is successfully uploaded, you can go ahead and upload the FreeTouchDeck.ino sketch to the ESP32. The settings under tools besides the Partition Scheme can be left to the default.

Go to "Sketch" and select "Upload". This may take a while because it is a large sketch.

Step 8: Printing a Case (optional)

Off course not necessary, but when you have built your FreeTouchDeck you can print a case for your FreeTouchDeck. This design will fit the screen and ESP32 with or without the combiner PCB.

The case is designed to be a press-fit. You could however add a touch of CA glue (crazy glue) to keep the top firmly attached to the bottom.

You can find the case on Thingiverse: https://www.thingiverse.com/thing:4661069

I printed it in PLA with a 0.2 mm layer height. The top doesn't need support if you print it face down. The bottom needs some minimal support if you print it with the opening down.

If you like to modify the case to your liking, you can find the Fusion 360 files on Github: https://github.com/DustinWatts/FreeTouchDeck/tree/master/case/ESP32_TFT_Combiner_Case

I've included some images of my slicer.

Step 9: First Boot

After uploading the sketch and all the files to the ESP, at first boot a touch calibration screen is displayed. This is so that FreeTouchDeck knows where all the corners are and can determine if a touch falls within the boundaries of a button.

A calibration file is saved on the ESP filesystem. So, if you re-upload files to the ESP using "ESP32 Sketch Data Upload", the calibration file is deleted and you will be presented with the calibration screen again.

The home screen has 6 buttons. These are all "menu buttons" in that they take you to an underlying menu. These buttons have a different colour as the function buttons in the menu's. On the home screen you will also find a "settings" menu. This will take you to a menu were you can enter the configurator.

Once the home screen is loaded, BLE is also started. You can now connect with your computer to the FreeTouchDeck. You might have to refresh your Bluetooth device list on your computer. After you see "FreeTouchDeck", you can connect to it. To test if Bluetooth works properly you can go in to the "Music" menu. And press "Mute" to see if a BLE connection is established.

Step 10: Configure Your FreeTouchDeck

You can now customize your FreeTouchDeck. FreeTouchDeck hosts a website on the ESP32 itself where you can configure the menu's and the button's each menu has. You can also customize the colors and upload your own logo's.

To start the configurator. Touch the bottom right button so go to the "Settings" page and then touch the "WiFi" button on the top left. Once the configurator has started you can open a web browser and go to freetouchdeck.local.

To learn more about how to use the configurator check out the Wiki on Github.

Step 11: Final Note and Troubleshooting

Troubleshooting

Not using the combiner PCB but using a breadboard can make for bad connections and a screen that doesn't seem to work. So if you seem to have a screen that is not working, double and triple check your connections!

Also if newer versions of the ESP32 core of TFT_eSPI (or any library for that matter) contain changes that need a code change, things might not work. I try to catch these changes and update the code accordingly, but it may not always happen straight away.

If you comment with any complications, please include the following information: