AI Passport Locker

One‑tap lock / unlock key for your Mac. Step away → press to lock; come back → press to unlock (it types your login password for you). Published on the FoloToy AI Passport community as AI Passport Locker; this repository is its open‑source implementation and also runs on any BLE‑capable ESP32.

The board pretends to be a Bluetooth (BLE HID) keyboard. Once you pair it with your Mac:

LOCK → sends Ctrl+Cmd+Q → macOS lock screen, instantly.
UNLOCK → blind‑types your stored login password + Enter on the lock screen.

Trigger either action with a serial command or an optional physical button — no display required. Built on ESP‑IDF + NimBLE.

⚠️ Security: the unlock password is stored in NVS in plaintext (flash encryption is off by default). Anyone who can desolder/read the flash can recover it. This is a convenience gadget for your own board + your own Mac. Treat the board like a key. The password is entered over serial and never appears in the source or the firmware image.

Why this exists

macOS filters BLE HID devices out of third‑party scans and is picky about pairing keyboards, which makes “roll‑your‑own BLE keyboard” surprisingly fiddly. This repo has the settings that actually work with macOS baked in (see Pairing below).

Hardware

Any ESP32 with Bluetooth LE: ESP32‑C3 / S3 / C6 / H2 / P4 (native USB‑Serial‑JTAG console) or the original ESP32 (change the console to UART).
Optional: two momentary push buttons (to GND) for physical LOCK / UNLOCK.

Build & flash

idf.py set-target esp32c3          # or esp32s3 / esp32c6 / ...
idf.py menuconfig                  # optional: "Mac Lock" → set button GPIOs / name
idf.py -p /dev/ttyACM0 flash monitor

menuconfig → Mac Lock:

BLE keyboard name — what the Mac shows (default esp32-mac-key).
LOCK / UNLOCK button GPIO — wire a button from that pin to GND (internal pull‑up). Leave at -1 to use serial commands only.

Set your password (over serial)

Open the serial monitor and type — the password is stored in NVS, never logged:

setpass your-login-password
status          # shows whether a password is set (not its value)
clearpass       # remove it

Pair with the Mac

Power the board; it advertises as your chosen name.
On the Mac: System Settings → Bluetooth, click the device to connect.
macOS asks for a pairing code. The board prints it to serial: >>> PAIRING CODE: 123456 <<< — type those digits on the Mac and press Enter.
macOS then opens the “Keyboard Setup Assistant” (Identifying Your Keyboard). A 2‑button board can’t press the keys it asks for — just quit it (⌘Q). Harmless; the keyboard stays paired and uses the default ANSI layout.

Renaming the board after pairing? Remove the old device from the Mac first — macOS caches the name by Bluetooth address.

Use it

Serial: type lock or unlock.
Buttons: press LOCK / UNLOCK.
Unlock only works on the normal lock screen (after login / wake). The very first cold‑boot FileVault screen comes up before Bluetooth, so use the built‑in keyboard there. It is blind typing — click the password field so it has focus before UNLOCK.

Commands (serial)

lock | unlock | setpass <pw> | clearpass | status | forget | help

forget deletes all BLE bonds (re‑pair / switch Macs).

How it works

ble_hid_kbd.c — a BLE HID keyboard (HOGP) with bonding + Secure Connections. macOS treats keyboards as security‑sensitive, so pairing uses MITM + DISPLAY_ONLY I/O capability: the board generates a 6‑digit passkey you type on the Mac.
Lock = HID report with modifiers Ctrl(0x01)|Cmd(0x08) + key Q(0x14).
Unlock = the US‑layout ASCII → HID map in hid_ascii_map.h, char by char, + Enter.
pw_store.c — password in NVS namespace unlock.

License

MIT — see LICENSE.

中文说明

AI Passport Locker —— 一键锁屏 / 一键解锁 Mac 的小工具。把任意带 BLE 的 ESP32 都能做成它。板子伪装成蓝牙(BLE HID) 键盘，和 Mac 配对后：锁屏发 Ctrl+Cmd+Q；解锁在锁屏界面盲敲你存的开机密码 + 回车。可用串口命令或可选实体按钮触发，无需屏幕。

⚠️ 密码明文存 NVS（默认未开 Flash 加密），拆板读 Flash 可提取——仅用于自己的板子 + 自己的 Mac。密码经串口灌入，不进源码/固件。

配对要点（macOS 的坑）：macOS 对键盘要求 MITM 配对码流程，本项目用 DISPLAY_ONLY—— 配对时串口会打印 >>> PAIRING CODE: 123456 <<<，在 Mac 上输入这串数字 + 回车。之后弹出的 “键盘设置助理”按 ⌘Q 退掉即可（不影响使用）。改名后要先在 Mac 蓝牙里移除旧设备（macOS 按地址缓存名字）。

编译烧录：idf.py set-target esp32c3 && idf.py flash monitor，串口 setpass <密码> 设密码， lock / unlock 触发。按钮引脚在 idf.py menuconfig → Mac Lock 里设。

AI Passport 锁屏器

关于