iPhone BLE bridge
An ESP32-S3 shows up to each iPhone as a Bluetooth mouse and keyboard. AssistiveTouch Perform Touch Gestures turns pointer clicks and drags into touches. The Mac talks to the board over USB serial.
Use when: you must drive an iPhone and WebDriverAgent is blocked (no Developer Mode, iOS 16 with no usable developer image, no cable).
Firmware, build script and the full doc: itsryanarmani/private-repo-32ef (hardware/, docs/ble-bridge.md). CLI: itsryanarmani/scripts (ble-bridge).
Set up the board
Do this before you pair any phone. Work in a itsryanarmani/private-repo-32ef checkout.
- Connect the ESP32-S3 to the Mac with USB.
- Flash it:
hardware/build.sh. The script builds and uploads the firmware. - Find the serial port:
ls /dev/cu.usbmodem*. - Send
pingover that port withble-bridge(itsryanarmani/scripts). The board must answerok. - Send
log. It must showadv=1. The board now advertises asPad xxxx.
Do not go on if ping fails. Fix the board first.
Gates
- Ask the user first for any outward-facing action: send, post, comment, like, follow, call, pay, delete, sign in, or grant a permission.
click,type,keyandscrollact on a real phone. Name the action before you run it.- Do not type a password or a code.
- Stop when a screen asks for approval. Follow the gates in
iphone-agent. - Apps may see the pointer. Start with passive actions.
Set up one phone
- Settings → Accessibility → Touch → AssistiveTouch: on. Perform Touch Gestures: on. Tracking Sensitivity: maximum.
- Devices → Bluetooth Devices → the board (
Pad xxxx) → accept the prompt. - Map the extra buttons. Open Devices → the board → Customize Additional Buttons. Send
@<slot> rclick, then pick Home. Send@<slot> mclick, then pick App Switcher.
If the phone says "pairing unsuccessful", forget the board in AssistiveTouch Devices and in Settings → Bluetooth, then pair again.
Commands
One line per command. Prefix @<slot> to pick a phone. The board answers ok or err <why>.
ping, list, log, home, move dx dy, press, release, click, rclick, mclick, scroll v h, type text, key cmd+space, forget.
rclick is Home and mclick is App Switcher after the mapping. Spotlight and cmd+h do not leave an app such as TikTok, so use rclick.
Pointer scale
After home, one count moves the pointer about 12.7 px (x) and 12.55 px (y) in a 608x1080 mirror frame. To reach frame point (X, Y): home, then move round(X/12.7) round(Y/12.55).
Wheel scroll is very slow. Drag instead: press, short move steps, release. Use 7 to 20 counts per drag. Larger drags overshoot because of momentum.
Why a third phone drops the first
The stock NimBLE settings hold three phones. These limits all cause it, and each needs its own fix:
- The connection limit, the bond store and the client-feature store are 3.
- The L2CAP channel pool is
3 x connections. At three links no channel is free, advertising stops (adv=0), and new phones see "pairing unsuccessful".
Flags fail in three ways, and each one wasted a flash cycle:
-DCONFIG_BT_NIMBLE_MAX_*loses to the core'ssdkconfig.h. Set theMYNEWT_VAL_*macros.- The connection macro has no
#ifndefguard inesp_nimble_cfg.h. Add the guard. compiler.cpp.extra_flagsdoes not reach the library's C files. Setcompiler.c.extra_flagstoo.
Use hardware/build.sh in private-repo-32ef. It does all three. To check a flag, preprocess one library file with the build's flags and read the macro.
Status
Verified: five phones linked at once on one board. Each slot answered ping and a pointer move. At five links the board shows adv=0. This is normal. For more than five phones, add a second board.
Whether apps can detect this input path is not proven. Start with passive actions.
Screen over USB
Since 2026-10-24 the screen can come over a USB cable. It needs no AirPlay and no Developer Mode. Use hardware/usbcap in itsryanarmani/private-repo-32ef (PR #12). Read docs/usb-screen.md there for the run steps.