1. Prerequisites and Version Requirements
The gate first: HarmonyOS Bluetooth HID requires the HarmonyOS central control, USB edition, version 3.2.0 or above. Below that version, Bluetooth HID settings does not appear in the right-click menu, and the script-side Bluetooth events are unavailable.
The mechanism is straightforward. Within HarmonyOS cluster control, the ESP32 board translates central control commands into Bluetooth HID events and sends them to the phone. The phone sees a HID Host, meaning it behaves as though an external keyboard were attached. The computer or central control reaches the board over serial or WiFi.
It does not conflict with HarmonyOS automation, HarmonyOS screen mirroring, or USB HID. They combine, or the board runs alone for taps and keys. In real projects the combination is more common: screenshots and image matching on the automation channel, taps on the board.
2. Step One: Choosing the Board and Firmware
You supply the board, the firmware is free. Settle four things before ordering, because any one of them wrong means reflashing.
| Item | Options | Note |
|---|---|---|
| Chip | ESP32-C3 or ESP32-S3 | Firmware differs |
| Board type | Welded pins or non-welded | Firmware is separate |
| Feature set | With keyboard or without | System keys and shortcuts need the keyboard build |
| Platform | HarmonyOS and Android USB, not iOS USB | Do not flash the iOS USB firmware |
Firmware sits in the product resources on the cloud drive: the HarmonyOS folder, the USB version, then the Bluetooth firmware directory. Flashing works the same as on Android, so there is no separate procedure to learn.
3. Step Two: Flashing
Two things matter when flashing. The chip model and board type must match the firmware exactly. And power-cycle the board afterward rather than leaving it attached to the flashing tool.
Close the flashing tool when you are done. While it holds the serial port, the central control cannot open it, and the symptom is a board that does not appear during binding or a MAC that cannot be read.
4. Step Three: Binding Bluetooth BLE
In the central control, select a connected device, open Bluetooth HID settings from the right-click menu, and click bind Bluetooth BLE.
In the dialog, choose the serial port. When the list is empty, clear filters such as show unbound only and force a refresh. If it still will not show, enter the MAC by hand, using the last eight characters of the Bluetooth MAC.
Where does that MAC come from? The board’s Bluetooth name is normally the last eight characters of its MAC, and the central control reads it automatically when the serial port is bound. Label the board when it arrives and label the matching phone, which saves a lot of cross-checking later.
After binding, the Bluetooth MAC column in the device list displays the hardware address. The mapping is UDID to Bluetooth MAC, one phone per board, which is also why a board serves a single phone at a time.
5. Step Four: Testing the Link
Binding only establishes the mapping. Whether data actually flows is a separate question, so test it.
On the phone, open Settings and then Bluetooth, search for the board, and pair. The name is the last eight characters of the MAC, and the icon may show as a keyboard or mouse. If the system asks to confirm an input device, allow it.
Back in the central control, open Bluetooth HID settings and click test Bluetooth BLE. Leave the transport on serial and click touch-and-hold or the HOME key.
If the phone responds, the whole path works. If not, work through this order: forget the device on the phone and pair again, press reset on the board, then test once more.
6. Step Five: Calling It from a Script
In HarmonyOS scripts, the Bluetooth object prefix is bleEvent, and the call order matters.
- Set the transport:
bleEvent.setSendCmdType(1)for serial,setSendCmdType(2)for network, which requires the board to be provisioned - Set the screen size with
bleEvent.setScreenSize(width, height), using the pixel dimensions of a screenshot - Open the serial port in serial mode with
bleEvent.openSerial - Then tap, swipe, and press:
clickPoint,swipeToPoint,systemKey,keyPressChar
systemKey covers system keys such as home, back, and recents. keyPressChar sends alphanumeric characters and shortcuts. Chinese long text should still go through proxy input with automation enabled.
There is a return convention worth noting: an empty value or empty string means success, and any other string is an error message. Check against that rather than a boolean.
Setting the screen size is the step people skip most often. Bluetooth taps use absolute pixel coordinates, so without the size set first the coordinates are off, and it has to be set again after any rotation change.
7. Troubleshooting Cheat Sheet
For a board that will not connect: hold reset for about five seconds and release, forget the device on the phone and search again, confirm the board serves only one phone, power-cycle after flashing, and toggle the phone’s Bluetooth off and on.
When the Bluetooth MAC in the central control will not update, confirm the version is at least 3.2.0 and the central control started normally. Reopen the binding dialog to check the current MAC, and unbind and force a rebind if needed.
For taps that do nothing or land wrong, look at three things in the script: whether the screen size is set first, whether the transport mode is correct, and whether the bound MAC matches the board on the current serial port.
The board LED helps identify the state: solid for about three seconds after pairing then off, a slow blink of roughly ten on disconnect, and a fast blink of roughly fifteen while searching.
One last reminder that is easy to overlook: USB debugging in Developer Options serves automation and screenshots, and it does not substitute for BLE pairing. Keep Bluetooth on, because if the pairing drops, nothing is listening for the events the script sends.
About EasyClick: A phone automation AI-agent platform covering Android no-root, iOS no-jailbreak (proxy / Bluetooth HID / OTG HID) and HarmonyOS Next, offering script development, Apple cluster control, local central control & mirroring, and cloud control systems. → Explore all products
Ready to build it for real?
Every approach in this article can be built with EasyClick capabilities on iEasyClick — full documentation, developer tools and automation products, free to try.