4-Direction Tilt Sensor

What it is

A square tilt switch with a metal roller inside, four red LEDs, and a six-pin header. Tip one edge of the board down and the roller rolls to that side of its cell and joins the two contacts there. Each contact is one of the lines A, B, C and D, so the four edges are four pairs: A–B, B–C, C–D and D–A.

It is not an accelerometer. It has four answers and none, no angle, and it cannot say level: the roller stays wherever it last rolled. For "which edge is down" or "has this box been tipped over", that is enough.

The page this replaces said it was four balls in four tubes, that each pin can be read on its own, that a flat board is a neutral state, and that two sides can both be closed near a diagonal. None of that is true of this switch.

You cannot read it like a button

Nothing on the board goes to GND. The roller only joins two lines to each other, so four pins set to INPUT_PULLUP read HIGH whichever way it leans. Your board finds the pair with a small scan:

1. Hold A LOW, read B and D. B LOW: left edge down. D LOW: header edge down.
2. Let A go, hold C LOW, read B and D. B LOW: top edge down. D LOW: right edge down.
3. Let everything go.

A released line is always an input with its pull-up, never an output driven HIGH, because the roller could join it to a line held LOW.

Which pin is which

Parts up, header at the bottom, reading left to right:

The back prints TK19 4-DIRECTIONS TILT SENSOR and no pin names. Turned over, the square pad is on the right, and it is still GND.

The lights, and VCC

Each line has a red LED from VCC through 1 kΩ, lit only while that line is held LOW. With only power wired they stay dark. Holding a line LOW lights its LED at:

Never 5V beside a 3.3 V board. The currents are worked out from a red LED's typical forward voltage rather than measured.

Wiring, in three lines

1. GND to your board's GND.
2. VCC to 5V on an Uno, 3V3 on an ESP32, ESP32-S3 or Pico.
3. A, B, C, D to four GPIOs: D2 to D5 on an Uno, GPIO 25, 26, 27 and 32 on an ESP32, GPIO 4 to 7 on an ESP32-S3, GP10 to GP13 on a Pico.

Example

// Uno: 2 3 4 5. ESP32: 25 26 27 32. ESP32-S3: 4 5 6 7. Pico: 10 11 12 13.
const int PIN_A = 4, PIN_B = 5, PIN_C = 6, PIN_D = 7;

void releaseAll() {             // every line an input with its pull-up
  pinMode(PIN_A, INPUT_PULLUP);
  pinMode(PIN_B, INPUT_PULLUP);
  pinMode(PIN_C, INPUT_PULLUP);
  pinMode(PIN_D, INPUT_PULLUP);
}

void holdLow(int pin) {         // the only way a line is ever driven
  digitalWrite(pin, LOW);
  pinMode(pin, OUTPUT);
}

const char* scanTilt() {
  releaseAll();
  holdLow(PIN_A);
  delayMicroseconds(10);
  bool ab = digitalRead(PIN_B) == LOW;
  bool da = digitalRead(PIN_D) == LOW;
  releaseAll();
  holdLow(PIN_C);
  delayMicroseconds(10);
  bool bc = digitalRead(PIN_B) == LOW;
  bool cd = digitalRead(PIN_D) == LOW;
  releaseAll();
  if (ab) return "left";
  if (da) return "header";
  if (bc) return "top";
  if (cd) return "right";
  return "none";
}

void setup() {
  Serial.begin(115200);
  releaseAll();
}

void loop() {
  Serial.println(scanTilt());
  delay(200);
}

from machine import Pin
import time

# ESP32: 25 26 27 32. ESP32-S3: 4 5 6 7. Pico: 10 11 12 13.
a, b, c, d = [Pin(n, Pin.IN, Pin.PULL_UP) for n in (4, 5, 6, 7)]

def release_all():              # every line an input with its pull-up
    for p in (a, b, c, d):
        p.init(Pin.IN, Pin.PULL_UP)

def scan_tilt():
    release_all()
    a.init(Pin.OUT, value=0)    # hold A LOW, read B and D
    time.sleep_us(10)
    ab, da = b.value() == 0, d.value() == 0
    release_all()
    c.init(Pin.OUT, value=0)    # hold C LOW, read B and D
    time.sleep_us(10)
    bc, cd = b.value() == 0, d.value() == 0
    release_all()
    if ab: return "left"
    if da: return "header"
    if bc: return "top"
    if cd: return "right"
    return "none"

while True:
    print(scan_tilt())
    time.sleep_ms(200)

Where to start

The handbook below is eleven short articles, each with a working figure. The first read is the whole build in six wires and one scan. No line goes to ground explains why the scan is needed at all.

If the LEDs puzzle you, the lights wait for you. If a level board reads a side, level is not a reading. For a project, a tip-over alarm is a box that knows it has been knocked over.