Fixing the ESP32 Marauder 2.8" TFT Touch & Display Issue — Step-by-step
Summary: If your ESP32 Marauder UI looks distorted or the touch doesn't register on a 2.8" ILI9341 TFT (often with XPT2046 touch controller), the problem is usually mismatched pin mapping or incorrect touch calibration. This post explains the full fix I used and provides the fixed repo link so you can flash a working firmware instantly.
Problem Overview
After following the v4 guide and flashing the recommended old_hardware firmware, my 2.8" TFT showed partial rendering and horizontal colored noise on the right side of the screen. The touch input either didn't respond or responded with strong misalignment.
What I changed (summary)
- Re-mapped SPI and control pins in the code to match the 30-pin ESP32 wiring.
- Configured the correct CS / DC / RESET pins for the ILI9341 display.
- Mapped T_CS and T_IRQ to correct GPIOs and tuned the touch calibration values for XPT2046.
- Recompiled using PlatformIO / Arduino with the same libraries but updated defines.
Recommended Wiring (common for many 2.8" SPI TFT + XPT2046)
Your display variant may differ — confirm the silkscreen on your module or the vendor docs. If you have a different mapping, update pins accordingly in code.
| TFT Pin | Suggested ESP32 (WROOM-32 30-pin) | Notes |
|---|---|---|
| VCC | 3.3V | Use 3.3V (not 5V) for ILI9341 logic |
| GND | GND | Common ground |
| CS (TFT CS) | GPIO 5 (D5) | Chip select - match in firmware |
| RESET | GPIO 22 | Display reset pin |
| DC / RS | GPIO 21 | Data/Command pin |
| MOSI (SDI) | GPIO 23 | SPI MOSI |
| SCK | GPIO 18 | SPI Clock |
| LED (Backlight) | 3.3V or controllable pin | Can be tied to 3.3V or PWM |
| T_CS (Touch CS) | GPIO 4 | XPT2046 CS for touch |
| T_IRQ (Touch IRQ) | GPIO 2 | Optional, used for interrupt-driven touch |
Note: If your display has SD pins (for microSD) and you are not using SD, leave them unconnected or wire carefully to avoid conflicts.
Code changes — what to edit
Open the display/touch config in the firmware and update the pin defines to match your wiring. Example defines (replace inside your project where pin mapping exists):
// Example display pin mapping (update these in your firmware)
#define TFT_MOSI 23
#define TFT_SCLK 18
#define TFT_CS 5
#define TFT_DC 21
#define TFT_RST 22
#define TFT_BL -1 // backlight, -1 if tied to 3.3V
// Touch controller (XPT2046)
#define TOUCH_CS 4
#define TOUCH_IRQ 2
// SPI bus used by the TFT
#define SPI_HOST HSPI_HOST
Also ensure the driver initialization uses ILI9341 and XPT2046. If the code uses custom display init sequences, keep them as-is but change the pins only.
Touch Calibration
If touches are misaligned after wiring is correct, you must calibrate the touch. Add or adjust calibration values (these are example values — you should run a calibration routine if available):
// Example touch calibration (XPT2046)
const int16_t TOUCH_MIN_X = 200;
const int16_t TOUCH_MAX_X = 3900;
const int16_t TOUCH_MIN_Y = 200;
const int16_t TOUCH_MAX_Y = 3900;
If the firmware contains a touch calibration routine or demo, run it and copy the recommended calibration constants into your configuration.
Build & Flash
Two common options: PlatformIO (recommended) or Arduino IDE
Tip: If the screen shows color bars or partial rendering after upload, double-check wiring (esp. CS/DC/RST) and ensure the display runs at 3.3V logic.PlatformIO (VS Code)
git clone https://github.com/they-call-me-electronerd/esp32-marauder
cd esp32-marauder
# Edit config files to update pin mapping & calibration
platformio run --target upload
Arduino IDE
# Open the project in Arduino IDE
# Set Board -> ESP32 Dev Module (or appropriate variant)
# Set Flash Size to 4MB (or match your module)
# Compile and Upload
Verification
After flashing and connecting:
- Power the ESP32 and watch boot logs on serial monitor (115200 baud). Some libraries print initialization messages.
- The UI should render without the noisy band on the right. If noise persists, try a different SPI frequency (lower it).
- Touch should register taps and menu selections. If not, re-run calibration or swap T_CS/T_IRQ pins if you chose different GPIOs.
Why this happens (short)
The most common reasons: wrong pin mapping, incompatible SPI frequency, or wrong touch driver settings. Modules from separate vendors often wire pins differently — always confirm the module pinout before copying example wiring.
Resources & Download
Fixed firmware and source are available here: https://github.com/they-call-me-electronerd/esp32-marauder
If you want to link to the original repo as reference: ESP32 Marauder (original)
Final Notes
If you try these steps and still have problems, please include:
- Exact display module model (any silkscreen or vendor link)
- Photos of the wiring (clear close-up)
- Which firmware file you flashed (branch & .bin name)
Share these on my GitHub issues page or reply here and I will help debug further.