QMC5883L + MPU6050 + 2.4 Inch TFT: Build an ESP32 Desk Car Gauge With a G-Force Needle, Tilt and a Compass - Compoden

QMC5883L + MPU6050 + 2.4 Inch TFT: Build an ESP32 Desk Car Gauge With a G-Force Needle, Tilt and a Compass

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

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.

Wiring diagram: ESP32-DevKitC driving a 2.4 inch ILI9341 SPI TFT on GPIO18, 23, 19, 5, 4 and 13, with an MPU6050 and a QMC5883L sharing I2C on GPIO21 and GPIO22, all on 3V3

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

  1. 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.
  2. Paste the sketch as car_gauge.ino, upload it, and open the Serial Monitor at 115200.
  3. 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.
  4. Turn it slowly through one full circle, flat on the desk, so the compass learns its offset.
  5. 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.

Back to blog

Open this project in the Soldr app → What is Soldr.ai → parts, wiring and code for what this guide builds