BLE Air Mouse

Turn the board into a wireless Bluetooth mouse — tilt to move the cursor, tap the touchscreen to click.

BleMouse QMI8658 IMU CST816T Touch BT 5 LE HID Gyro dead-zone Arduino_GFX

What it does

The QMI8658 gyroscope (256 dps range, 128 LSB/dps) streams angular velocity at ~120 Hz. The sketch maps gyro X/Y directly to mouse delta X/Y after applying a dead-zone of ±1.5 °/s to eliminate drift at rest.

The CST816T capacitive touch controller is polled each loop — a finger-down event fires a MOUSE_LEFT click via the BLE HID stack. The ST7789V2 display shows a live crosshair that tracks the simulated cursor position.

# Control Flow

StepDetail
IMU read12 bytes from QMI8658 starting at 0x35 (AX_L). Gyro X/Y extracted from bytes 6–9 (raw[3], raw[4]). Scale: 128 LSB/°/s at 256 dps range.
Dead-zoneIf |gy| < 1.5 → dx = 0; if |gx| < 1.5 → dy = 0. Eliminates jitter when held still.
Sensitivity scaledx = gy × 0.35, clamped to int8_t (–127 … 127). Lower SENSITIVITY = slower, more precise.
BLE movebleMouse.move(mx, my) only called when mx ≠ 0 or my ≠ 0 — avoids unnecessary HID reports.
Touch clickRising edge on touch (lastTouch = false → true) fires bleMouse.click(MOUSE_LEFT) once per tap.
Display update~30 fps (33 ms timer). Erases old crosshair in BLACK, redraws at new position in CYAN. Click briefly flashes WHITE.

# IMU Configuration

RegisterValueEffect
CTRL1 (0x02)0x40Address auto-increment on burst reads
CTRL2 (0x03)0x13Accelerometer ±4 g, 250 Hz ODR
CTRL3 (0x04)0x43Gyroscope ±256 dps, 250 Hz ODR — tighter range for cursor precision
CTRL7 (0x08)0x03Enable both accel and gyro

# Hardware Wiring

Display (SPI)

DC=4, CS=5, SCK=6, MOSI=7
RST=8, BL=15
Display: ST7789V2 240×280 IPS
row_offset=20

IMU + Touch (I2C)

SDA=11, SCL=10  400 kHz
QMI8658 → 0x6B  (6-axis IMU)
CST816T → 0x15  (touch)

# BLE HID

Uses the T-vK/ESP32-BLE-Mouse library. The device advertises as "ESP32 Air Mouse" (manufacturer: Waveshare). Once paired, the host OS sees it as a standard HID mouse — no drivers needed.

Pairing

  • Power on the board
  • Display shows SEARCHING… (red bar)
  • Pair from host Bluetooth settings — look for ESP32 Air Mouse
  • Display switches to CONNECTED (green bar)

Tuning

SENSITIVITY = 0.35f  // higher = faster
DEAD_ZONE   = 1.5f   // °/s threshold
Poll rate   = 8 ms   // ~120 Hz

Lower SENSITIVITY for fine-grained desktop use; raise DEAD_ZONE in vibration-prone environments.

# Source

Full sketch in the ESP32-S3-LCD repo — sketches/ble_air_mouse/ble_air_mouse.ino.

git clone https://github.com/binRick/ESP32-S3-LCD
bash flash-sketch-002-ble-air-mouse.sh