QMC5883L + MPU6050 + 2.4 Inch TFT: Build an ESP32 Desk Car Gauge With a G-Force Needle, Tilt and a Compass
Share
Custom digital gauges are everywhere right now, and most start the same way: a colour screen, a motion sensor and a compass. This is that idea as a desk build. An ESP32 drives a 2.4 inch ILI9341 TFT showing a round G-force needle, pitch and roll, and a compass heading. No car, no CAN bus, just three modules on a breadboard you can tilt, turn and flick.
Soldr designed this build, the parts list, the pin plan and the code around parts that can be shipped to you in India. Soldr is Compoden's AI, AI built on a catalog, so everything below is a part you can order here. We only added the breadboard, since three parts share power and I2C. If anything is missing, incorrect, or doesn't work as expected, let us know so it can be fixed.
What you need
- ESP32-DEVKITC Development Board (Black)
- 2.4 Inch TFT LCD Display ILI9341 (SPI, 240x320)
- MPU6050 6-Axis Gyro and Accelerometer Module
- QMC5883L 3-Axis Compass Module (I2C)
- MB102 830-Point Breadboard with Jumper Wires
- Jumper Wire Combo (M-M, M-F, F-F)
- USB to Micro-USB Data Cable (1 m) for the ESP32
Step 1: Wire the screen and the two sensors
Seventeen connections, all at 3.3V. Put 3V3, GND, SDA and SCL on breadboard rails first.

| Part pin | ESP32 pin |
|---|---|
| TFT VCC | ESP32 3V3 |
| TFT GND | ESP32 GND |
| TFT SCK | GPIO18 |
| TFT MOSI (SDI) | GPIO23 |
| TFT MISO (SDO) | GPIO19 |
| TFT CS | GPIO5 |
| TFT DC | GPIO4 |
| TFT RST | GPIO13 |
| TFT LED (backlight) | ESP32 3V3 |
| MPU6050 VCC / GND | 3V3 / GND |
| MPU6050 SDA / SCL | GPIO21 / GPIO22 |
| QMC5883L VCC / GND | 3V3 / GND |
| QMC5883L SDA / SCL | GPIO21 / GPIO22 (same rows as the MPU6050) |
| Power | ESP32 micro-USB port (computer or a 5V USB charger) |
A few notes so it works the first time:
- Everything runs at 3.3V. The ILI9341 is 3.3V logic and not 5V tolerant, so the ESP32 is a perfect match with no level shifter. Both sensor modules are happy on 3V3.
- Two sensors, one I2C bus. Both sensors sit on the same SDA and SCL rows. They don't clash: the MPU6050 is at 0x68, the QMC5883L at 0x0D.
- Check the headers. If a module came with its pin strip loose, solder it on first. Pins just pushed into the holes give flaky I2C.
- Keep the compass away from metal. Keep the QMC5883L a few centimetres from the USB cable, the ESP32 and anything steel.
Step 2: Upload the Soldr firmware
Soldr generated and compiled this sketch for the ESP32-DevKitC; it's shown exactly as generated. Paste it as car_gauge.ino and upload with the board set to ESP32 Dev Module.
// legend: [SOLDR] build · [INIT] init · [TEST] self-test · [DATA] telemetry · [WARN]/[ERROR] fault · [FIX] likely remedy
//
// Digital car gauge: round G-force needle + pitch/roll tilt + compass heading
//
// WIRING (ESP32-DEVKITC, all 3.3V logic)
// WIRING - generated from the same pin plan as the Wiring tab (follow the Wiring tab if in doubt):
// 3V3 -> 2.4 inch TFT LCD Display ILI9341 S VCC
// GND -> 2.4 inch TFT LCD Display ILI9341 S GND
// GPIO18 -> 2.4 inch TFT LCD Display ILI9341 S SCK
// GPIO23 -> 2.4 inch TFT LCD Display ILI9341 S MOSI
// GPIO19 -> 2.4 inch TFT LCD Display ILI9341 S MISO
// GPIO5 -> 2.4 inch TFT LCD Display ILI9341 S CS/SS
// 3V3 -> 2.4 inch TFT LCD Display ILI9341 S LED / BL (backlight)
// GPIO4 -> 2.4 inch TFT LCD Display ILI9341 S DC
// GPIO13 -> 2.4 inch TFT LCD Display ILI9341 S RST
// 3V3 -> MPU6050 3-Axis Gyro/Accel Sensor M VCC
// GND -> MPU6050 3-Axis Gyro/Accel Sensor M GND
// GPIO21 -> MPU6050 3-Axis Gyro/Accel Sensor M SDA
// GPIO22 -> MPU6050 3-Axis Gyro/Accel Sensor M SCL
// 3V3 -> QMC5883L Compass Module VCC
// GND -> QMC5883L Compass Module GND
// GPIO21 -> QMC5883L Compass Module SDA
// GPIO22 -> QMC5883L Compass Module SCL
// USB port -> ESP32-DEVKITC Development Board powered from its own USB port (a cable to a computer or a 5 V USB charger)
//
// Libraries (Library Manager): Adafruit GFX Library, Adafruit ILI9341,
// Adafruit MPU6050, Adafruit Unified Sensor, QMC5883LCompass
#include <Arduino.h>
#include <Wire.h>
#include <SPI.h>
#include <math.h>
#include <Adafruit_GFX.h>
#include <Adafruit_ILI9341.h>
#include <Adafruit_MPU6050.h>
#include <Adafruit_Sensor.h>
#include <QMC5883LCompass.h>
#define SOLDR_DEBUG 1
#define TFT_CS_PIN 5
#define TFT_DC_PIN 4
#define TFT_RST_PIN 13
#define SPI_SCK_PIN 18
#define SPI_MISO_PIN 19
#define SPI_MOSI_PIN 23
#define I2C_SDA_PIN 21
#define I2C_SCL_PIN 22
#define QMC_ADDR 0x0D
#define MAG_DECLINATION_DEG 0.0f // set your local magnetic declination
#define G_FULL_SCALE 2.0f // needle full-scale in G
// Colours (RGB565)
#define C_BG 0x0000
#define C_FG 0xFFFF
#define C_DIM 0x7BEF
#define C_ACCENT 0x07FF
#define C_NEEDLE 0xF800
#define C_HEAD 0x10A2
// Layout (240x320 portrait)
#define GAUGE_CX 120
#define GAUGE_CY 118
#define GAUGE_R 78
#define COMP_CX 55
#define COMP_CY 278
#define COMP_R 36
Adafruit_ILI9341 tft(TFT_CS_PIN, TFT_DC_PIN, TFT_RST_PIN);
Adafruit_MPU6050 mpu;
QMC5883LCompass compass;
bool mpuOk = false;
bool qmcOk = false;
int okCount = 0;
int failCount = 0;
// Filtered values
float gFilt = 1.0f;
float pitchDeg = 0, rollDeg = 0;
float pitchZero = 0, rollZero = 0;
float hdgSin = 0, hdgCos = 1;
float headingDeg = 0;
// Compass hard-iron auto-calibration
int magMinX = 32767, magMaxX = -32768, magMinY = 32767, magMaxY = -32768;
// Last drawn state (draw only on change)
int lastNeedleDeg = -999;
int lastCompDeg = -999;
int lastG100 = -999, lastPitch = -999, lastRoll = -999, lastHdg = -999;
unsigned long lastSample = 0;
unsigned long lastLog = 0;
const unsigned long SAMPLE_MS = 25;
const unsigned long LOG_MS = 500;
static inline float deg2rad(float d) { return d * (float)M_PI / 180.0f; }
// ---------- drawing ----------
void gaugePoint(float angDeg, float radius, int &x, int &y) {
float a = deg2rad(angDeg);
x = GAUGE_CX + (int)lroundf(cosf(a) * radius);
y = GAUGE_CY + (int)lroundf(sinf(a) * radius);
}
void drawGaugeStatic() {
tft.drawCircle(GAUGE_CX, GAUGE_CY, GAUGE_R, C_FG);
tft.drawCircle(GAUGE_CX, GAUGE_CY, GAUGE_R - 1, C_DIM);
for (int i = 0; i <= 8; i++) {
float ang = 135.0f + 270.0f * i / 8.0f;
int x1, y1, x2, y2;
float inner = (i % 4 == 0) ? GAUGE_R - 14 : GAUGE_R - 8;
gaugePoint(ang, GAUGE_R - 2, x1, y1);
gaugePoint(ang, inner, x2, y2);
tft.drawLine(x1, y1, x2, y2, (i % 4 == 0) ? C_ACCENT : C_FG);
}
tft.setTextSize(1);
tft.setTextColor(C_DIM, C_BG);
int lx, ly;
gaugePoint(135, GAUGE_R - 26, lx, ly);
tft.setCursor(lx - 2, ly - 3); tft.print("0");
gaugePoint(270, GAUGE_R - 26, lx, ly);
tft.setCursor(lx - 2, ly - 3); tft.print("1");
gaugePoint(405, GAUGE_R - 26, lx, ly);
tft.setCursor(lx - 2, ly - 3); tft.print("2");
}
void drawThickLine(int x0, int y0, int x1, int y1, uint16_t col) {
tft.drawLine(x0, y0, x1, y1, col);
tft.drawLine(x0 + 1, y0, x1 + 1, y1, col);
tft.drawLine(x0, y0 + 1, x1, y1 + 1, col);
}
void drawGaugeNeedle(int angDeg, uint16_t col) {
int tx, ty;
gaugePoint((float)angDeg, GAUGE_R - 16, tx, ty);
drawThickLine(GAUGE_CX, GAUGE_CY, tx, ty, col);
}
void updateGaugeNeedle(float g) {
float f = constrain(g / G_FULL_SCALE, 0.0f, 1.0f);
int ang = (int)lroundf(135.0f + 270.0f * f);
if (ang == lastNeedleDeg) return;
if (lastNeedleDeg != -999) drawGaugeNeedle(lastNeedleDeg, C_BG);
drawGaugeStatic();
drawGaugeNeedle(ang, C_NEEDLE);
tft.fillCircle(GAUGE_CX, GAUGE_CY, 5, C_FG);
lastNeedleDeg = ang;
}
void compassPoint(float angFromUpDeg, float radius, int &x, int &y) {
float a = deg2rad(angFromUpDeg);
x = COMP_CX + (int)lroundf(sinf(a) * radius);
y = COMP_CY - (int)lroundf(cosf(a) * radius);
}
void drawCompassNeedle(int angDeg, bool erase) {
int nx, ny, sx, sy;
compassPoint((float)angDeg, COMP_R - 4, nx, ny);
compassPoint((float)angDeg + 180.0f, COMP_R - 14, sx, sy);
tft.drawLine(COMP_CX, COMP_CY, nx, ny, erase ? C_BG : C_NEEDLE);
tft.drawLine(COMP_CX + 1, COMP_CY, nx + 1, ny, erase ? C_BG : C_NEEDLE);
tft.drawLine(COMP_CX, COMP_CY, sx, sy, erase ? C_BG : C_FG);
}
void drawCompassStatic() {
tft.drawCircle(COMP_CX, COMP_CY, COMP_R, C_FG);
tft.drawCircle(COMP_CX, COMP_CY, COMP_R + 1, C_DIM);
tft.setTextSize(1);
tft.setTextColor(C_ACCENT, C_BG);
tft.setCursor(COMP_CX - 2, COMP_CY - COMP_R - 11); tft.print("N");
}
void updateCompassNeedle(float hdg) {
int ang = (int)lroundf(-hdg); // needle points to magnetic north
while (ang < 0) ang += 360;
ang %= 360;
if (ang == lastCompDeg) return;
if (lastCompDeg != -999) drawCompassNeedle(lastCompDeg, true);
drawCompassStatic();
drawCompassNeedle(ang, false);
tft.fillCircle(COMP_CX, COMP_CY, 3, C_FG);
lastCompDeg = ang;
}
const char *cardinal(float hdg) {
static const char *names[8] = {"N", "NE", "E", "SE", "S", "SW", "W", "NW"};
int idx = (int)((hdg + 22.5f) / 45.0f) % 8;
return names[idx];
}
void drawStaticUI() {
tft.fillScreen(C_BG); // once, at setup only
tft.fillRect(0, 0, 240, 24, C_HEAD);
tft.setTextSize(2);
tft.setTextColor(C_FG, C_HEAD);
tft.setCursor(38, 5);
tft.print("CAR GAUGE");
drawGaugeStatic();
drawCompassStatic();
tft.setTextSize(1);
tft.setTextColor(C_DIM, C_BG);
tft.setCursor(110, 236); tft.print("HEADING");
tft.setCursor(110, 276); tft.print("TILT");
}
void updateReadouts(float g, float pitch, float roll, float hdg) {
char buf[24];
int g100 = (int)lroundf(g * 100.0f);
int p = (int)lroundf(pitch);
int r = (int)lroundf(roll);
int h = ((int)lroundf(hdg)) % 360;
if (g100 != lastG100) {
snprintf(buf, sizeof(buf), "%4d.%02d G ", g100 / 100, g100 % 100);
tft.setTextSize(3);
tft.setTextColor(C_FG, C_BG);
tft.setCursor(36, 206);
tft.print(buf);
lastG100 = g100;
}
if (h != lastHdg) {
snprintf(buf, sizeof(buf), "%3d %-2s ", h, cardinal(hdg));
tft.setTextSize(3);
tft.setTextColor(C_ACCENT, C_BG);
tft.setCursor(110, 248);
tft.print(buf);
lastHdg = h;
}
if (p != lastPitch) {
snprintf(buf, sizeof(buf), "P %+4d ", p);
tft.setTextSize(2);
tft.setTextColor(C_FG, C_BG);
tft.setCursor(110, 288);
tft.print(buf);
lastPitch = p;
}
if (r != lastRoll) {
snprintf(buf, sizeof(buf), "R %+4d ", r);
tft.setTextSize(2);
tft.setTextColor(C_FG, C_BG);
tft.setCursor(110, 304);
tft.print(buf);
lastRoll = r;
}
}
// ---------- sensors ----------
bool readAccel(float &ax, float &ay, float &az) {
sensors_event_t a, g, t;
mpu.getEvent(&a, &g, &t);
ax = a.acceleration.x / 9.80665f;
ay = a.acceleration.y / 9.80665f;
az = a.acceleration.z / 9.80665f;
return true;
}
void accelToTilt(float ax, float ay, float az, float &pitch, float &roll) {
pitch = atan2f(-ax, sqrtf(ay * ay + az * az)) * 180.0f / (float)M_PI;
roll = atan2f(ay, az) * 180.0f / (float)M_PI;
}
void calibrateLevel() {
// Keep the unit still and level: average tilt becomes the zero reference.
// MPU6050 accel needs calibration; this removes the mounting-angle offset only.
float sp = 0, sr = 0;
const int N = 50;
for (int i = 0; i < N; i++) {
float ax, ay, az, p, r;
readAccel(ax, ay, az);
accelToTilt(ax, ay, az, p, r);
sp += p; sr += r;
delay(10);
}
pitchZero = sp / N;
rollZero = sr / N;
}
void updateCompassHeading() {
compass.read();
int mx = compass.getX();
int my = compass.getY();
if (mx < magMinX) magMinX = mx;
if (mx > magMaxX) magMaxX = mx;
if (my < magMinY) magMinY = my;
if (my > magMaxY) magMaxY = my;
float cx = mx, cy = my;
if ((magMaxX - magMinX) > 200 && (magMaxY - magMinY) > 200) {
cx = mx - (magMaxX + magMinX) / 2.0f;
cy = my - (magMaxY + magMinY) / 2.0f;
}
float h = atan2f(cy, cx) * 180.0f / (float)M_PI + MAG_DECLINATION_DEG;
// circular low-pass so 359->0 does not swing the needle backwards
hdgSin += 0.2f * (sinf(deg2rad(h)) - hdgSin);
hdgCos += 0.2f * (cosf(deg2rad(h)) - hdgCos);
float s = atan2f(hdgSin, hdgCos) * 180.0f / (float)M_PI;
if (s < 0) s += 360.0f;
headingDeg = s;
}
void setup() {
Serial.begin(115200);
delay(300);
#if SOLDR_DEBUG
Serial.println();
Serial.println("[SOLDR] Car Gauge | board:ESP32-DEVKITC | v1.0");
#endif
Wire.begin(I2C_SDA_PIN, I2C_SCL_PIN);
SPI.begin(SPI_SCK_PIN, SPI_MISO_PIN, SPI_MOSI_PIN, TFT_CS_PIN);
tft.begin();
tft.setRotation(0);
tft.fillScreen(C_BG);
okCount++;
#if SOLDR_DEBUG
Serial.println("[INIT] ILI9341 TFT: OK (begin() gives no presence check)");
Serial.println("[FIX] ILI9341 TFT: if the screen stays dark check LED/BL->3V3, CS=5 DC=4 RST=13, SPI on 18/23");
#endif
mpuOk = mpu.begin(); // addr 0x68
if (mpuOk) {
mpu.setAccelerometerRange(MPU6050_RANGE_4_G);
mpu.setFilterBandwidth(MPU6050_BAND_21_HZ);
okCount++;
#if SOLDR_DEBUG
Serial.println("[INIT] MPU6050: OK");
#endif
} else {
failCount++;
#if SOLDR_DEBUG
Serial.println("[INIT] MPU6050: FAIL (not found at 0x68)");
Serial.println("[FIX] MPU6050: check SDA=21 SCL=22, 3V3 power, AD0 low (0x68), solder joints");
#endif
}
Wire.beginTransmission(QMC_ADDR);
qmcOk = (Wire.endTransmission() == 0);
if (qmcOk) {
compass.init();
compass.setSmoothing(5, true);
okCount++;
#if SOLDR_DEBUG
Serial.println("[INIT] QMC5883L: OK");
#endif
} else {
failCount++;
#if SOLDR_DEBUG
Serial.println("[INIT] QMC5883L: FAIL (no ACK at 0x0D)");
Serial.println("[FIX] QMC5883L: check SDA/SCL wiring and 3V3; some GY-271 boards carry an HMC5883L at 0x1E instead");
#endif
}
drawStaticUI();
if (mpuOk) {
tft.setTextSize(1);
tft.setTextColor(C_ACCENT, C_BG);
tft.setCursor(60, 30);
tft.print("Hold level...");
calibrateLevel();
tft.fillRect(60, 30, 130, 10, C_BG);
drawGaugeStatic();
#if SOLDR_DEBUG
float ax, ay, az;
readAccel(ax, ay, az);
Serial.printf("[TEST] MPU6050: ax=%.2f ay=%.2f az=%.2f g, zeroP=%.1f zeroR=%.1f\n",
ax, ay, az, pitchZero, rollZero);
#endif
} else {
tft.setTextSize(1);
tft.setTextColor(C_NEEDLE, C_BG);
tft.setCursor(50, 30);
tft.print("MPU6050 NOT FOUND");
}
if (qmcOk) {
// first sample after the module has had time to start
delay(100);
compass.read();
#if SOLDR_DEBUG
Serial.printf("[TEST] QMC5883L: x=%d y=%d z=%d\n", compass.getX(), compass.getY(), compass.getZ());
#endif
}
#if SOLDR_DEBUG
Serial.printf("[READY] %d OK / %d FAIL\n", okCount, failCount);
#endif
}
void loop() {
unsigned long now = millis();
if (now - lastSample >= SAMPLE_MS) {
lastSample = now;
if (mpuOk) {
float ax, ay, az, p, r;
readAccel(ax, ay, az);
float gMag = sqrtf(ax * ax + ay * ay + az * az);
gFilt += 0.25f * (gMag - gFilt);
accelToTilt(ax, ay, az, p, r);
pitchDeg += 0.25f * ((p - pitchZero) - pitchDeg);
rollDeg += 0.25f * ((r - rollZero) - rollDeg);
}
if (qmcOk) {
updateCompassHeading();
}
updateGaugeNeedle(gFilt);
updateCompassNeedle(headingDeg);
updateReadouts(gFilt, pitchDeg, rollDeg, headingDeg);
}
#if SOLDR_DEBUG
if (now - lastLog >= LOG_MS) {
lastLog = now;
Serial.printf("[DATA] g=%.2f pitch=%.1f roll=%.1f hdg=%.0f\n", gFilt, pitchDeg, rollDeg, headingDeg);
if (!mpuOk) Serial.println("[WARN] MPU6050: not initialised, G and tilt frozen");
if (!qmcOk) Serial.println("[WARN] QMC5883L: not initialised, heading frozen");
}
#endif
}
How it works
- Every 25 ms the sketch reads the MPU6050 (set to plus or minus 4 G) and works out total acceleration. That's the needle: 0 to 2 G across the dial, about 1 G at rest because gravity is always there.
- So it's a G-meter, not a tilt meter. Slow tilting barely moves it; a flick swings it.
- Pitch and roll come from the same accelerometer. At boot it shows Hold level... and averages 50 readings over half a second; that angle becomes zero.
- The compass calibrates itself: as you turn the board it records the lowest and highest readings on X and Y, then removes the offset from nearby metal (the hard-iron error).
- Heading uses a circular filter, so 359 to 0 doesn't swing the needle the long way round. You get degrees plus N, NE, E and so on, and the small needle points to magnetic north.
- It only redraws what changed, so there's no flicker.
Step 3: Try it
- In the Arduino IDE, install the ESP32 board package plus Adafruit GFX Library, Adafruit ILI9341, Adafruit MPU6050, Adafruit Unified Sensor and QMC5883LCompass, and pick ESP32 Dev Module.
- Paste the sketch as car_gauge.ino, upload it, and open the Serial Monitor at 115200.
- Keep it flat and still while it says Hold level... You should see [INIT] lines for all three parts, then [READY] 3 OK / 0 FAIL.
- Turn it slowly through one full circle, flat on the desk, so the compass learns its offset.
- Now flick it, tilt it and turn it.
If something's off
- White or blank screen: check LED to 3V3, then CS on 5, DC on 4 and RST on 13. The sketch can't detect the screen, so it says OK even when it isn't wired.
- QMC5883L: FAIL (no ACK at 0x0D): check SDA and SCL. Some compass boards carry an HMC5883L at 0x1E instead, which this library doesn't talk to.
- MPU6050: FAIL: check SDA on 21, SCL on 22, and that AD0 isn't pulled high (that moves it to 0x69).
- Heading is way off: it's only right held flat (no tilt compensation). Redo the full-circle turn away from metal, and set MAG_DECLINATION_DEG for where you live if you want.
How Soldr designs this from the idea
Want a peak-G marker or a lap timer? Describe the idea at soldr.ai. Soldr designs hardware from the idea: it asks which board you want, picks parts from the Compoden catalog, assigns the pins, gives you the wiring and writes the firmware, then compiles it for your board. For this one the idea was a digital car gauge with a round G needle, tilt and a compass that move live.
Put it in a small box and it's the most satisfying thing on your desk to flick.