Cardputer Keyboard & Mouse

English | 简体中文 | 繁體中文 | Italiano | Français | Português

Turn an M5Stack Cardputer Adv into a pocket keyboard + mouse for any computer, phone or tablet — over Bluetooth LE or USB-C.

• ⌨️ Keyboard — all 56 keys send standard HID keycodes (even works in BIOS over USB)
• 🖱️ Tilt mouse — tilt the device to move the cursor, using the built-in accelerometer (arrow-key cursor as fallback)
• 📶 3 Bluetooth slots — stay paired with up to 3 devices and hop between them
• ⚙️ On-device settings menu — settings saved to the TF card
• Works with Windows / macOS / Linux / Android / iPadOS / iOS

Quick start

1. Flash the firmware — see Flashing.
2. Bluetooth (default): pair Cardputer-Keyboard-Mouse from your device's Bluetooth settings. No PIN needed.
3. Prefer USB? Hold BtnA ~0.7 s to open the menu, pick Transport → USB (the device reboots), then connect a USB-C data cable.
4. Type away. Press Fn+Space to switch input mode: Keyboard → Mouse → Keyboard+Mouse.

The top status bar shows: connection state (OK / ADV), input mode ([KEY] / [MOUSE] / [K+M]), CAPS, tilt sensitivity S1–S5, and battery.

Input modes

Mode	Keyboard	Cursor
Keyboard	all keys type	off
Mouse	keys become mouse controls	tilt to move — hold any key to move (clutch)
Keyboard+Mouse (default)	all keys type	tilt always on, paused while typing

Mouse mode keys

Laid out like arrow keys on ; , . /:

Key	Action
, / Enter / BtnA	left button
/	right button
m	middle button
; / .	wheel up / down
any other key (hold)	clutch — cursor moves only while held

Keyboard+Mouse mode extras

Key	Action
BtnA short press	left click
Opt + , / / / m	left / right / middle button
Opt + ; / .	wheel up / down
Opt quick tap	one GUI/Win/Cmd key tap

While held, Opt acts as the local mouse prefix and is not sent to the host. For GUI-key combos (e.g. Win+C), use Keyboard mode, where Opt is a normal GUI modifier.

Arrow-key cursor

Used when you set Cursor source = arrows in the menu, or automatically if the motion sensor fails. Mouse mode only:

Key	Action
; , . /	move up / left / down / right (accelerates while held)
j / k	left / right button
u / n	wheel up / down
Enter / BtnA	left button

Fn layer

Modifiers: Ctrl, Shift (Aa), Alt, Opt = GUI/Win/Cmd. Fn is local and never sent to the host.

Key	Fn layer		Key	Fn layer
`	Esc		u	PgUp
1 … 9, 0	F1 … F9, F10		i	Insert
- / =	F11 / F12		p	PrintScreen
Backspace	Delete		a	CapsLock
e	End		d	PgDn
h	Home		;	↑
, / . / /	← / ↓ / →		Space	switch input mode

Everything else types its printed symbol (US layout; the host's layout applies).

Settings menu

Hold BtnA ~0.7 s to open/close (input to the host is paused while open). Navigate with ; up, . down, Enter select, ` / Backspace back.

Item	What it does
Transport	BLE / USB (saves and reboots)
BLE host slot	1 / 2 / 3 — each slot is its own Bluetooth identity
Clear pairing	removes the bonds of all 3 slots — also remove the device on the hosts
Sensitivity	tilt cursor speed, 1–5
Clutch mode	default / hold-to-move / hold-to-freeze / always-on
Cursor source	tilt / arrow keys
Recalibrate tilt	hold your preferred neutral pose still for ~1 s
Brightness	screen backlight, 20-100% in 20% steps (default 80%)
Device name	cycles presets (free text: edit the settings file)
About	version + settings backend

Settings are stored in /kbmouse/settings.txt on the TF card (plain key=value, safe to hand-edit), with fallback to internal flash when no card is present.

Flashing

Pre-built images

make release

builds both distribution images into release/:

File	How to flash
Cardputer-Keyboard-Mouse-full.bin	write at offset 0x0 with esptool / M5Burner
Cardputer-Keyboard-Mouse-app.bin	copy to the TF card and install from M5Launcher

esptool.py --chip esp32s3 write_flash 0x0 release/Cardputer-Keyboard-Mouse-full.bin

Build from source (PlatformIO)

pio run -e cardputer-adv            # build
pio run -e cardputer-adv -t upload  # flash over USB
pio test -e native                  # unit tests (no hardware needed)

If the USB port doesn't show up (first flash / broken firmware), enter download mode: power off → hold G0/BtnA → connect USB → release.

M5Launcher notes: settings live on the TF card, so they survive switching firmwares; BLE pairings may be lost when switching — re-pair afterwards. This firmware never touches G5 and never erases the whole NVS.

Tips & troubleshooting

• The screen turns off after 20 s of inactivity to save power — any key, click or tilt movement wakes it instantly. Input keeps working while the screen is off.
• Keep the device still for ~1 s at boot — it captures the neutral pose (the screen shows CALIBRATING). Whenever cursor movement engages, the pose at that moment becomes the new center, so the cursor never drifts on its own.
• Mouse pointer on iPhone/iPad: enable Settings → Accessibility → Touch → AssistiveTouch. The keyboard works out of the box.
• Bluetooth stopped working after re-pairing? Remove the device from the host's Bluetooth list, use Clear pairing in the menu, and pair again.
• Motion sensor not detected? The firmware switches to the arrow-key cursor automatically and says so on screen.
• Tilt direction reversed on your hardware? Adjust rollSign / pitchSign in src/core/mouse_engine.h.
• Re-flashing always works: the USB port stays a serial console in both transports — no boot-button dance needed. In USB transport the device is a composite CDC + HID keyboard + HID mouse and types in BIOS/UEFI.