1. Why HarmonyOS Needs a Bluetooth Path at All
The default approach in HarmonyOS cluster control is a data cable, one per device, which is stable and low latency. Once the device count grows, though, the cables become the problem: not enough USB ports, tangled wiring, and a rack that gets harder to maintain every month.
HarmonyOS Bluetooth HID exists for that situation. The idea is to make the phone believe it has an external keyboard attached. The computer or the HarmonyOS central control talks to an ESP32 board over serial or WiFi, and the board sends Bluetooth HID events to the phone. As far as the phone is concerned, nothing unusual is happening.
This path does not conflict with HarmonyOS automation scripts, HarmonyOS screen mirroring, or USB HID. It can run alone or alongside them. In practice the useful pattern is to split the channels: screenshots and image matching go through automation, taps go through the board. For teams running Bluetooth cluster control at scale, that separation is what keeps a rack manageable.
2. Decide What to Buy First
You buy the board yourself, and the firmware is free. Before ordering, settle four choices. Get any one wrong and you are reflashing.
| Choice | Options | Note |
|---|---|---|
| Chip | ESP32-C3 or ESP32-S3 | Separate firmware for each |
| Board type | Welded pins or non-welded | Firmware is split accordingly |
| Feature set | With keyboard or without | System keys and shortcuts need the keyboard build |
| Platform | HarmonyOS or Android USB | Do not flash the iOS USB firmware |
Firmware lives in the product resources on the cloud drive, under the HarmonyOS folder, then the USB version, then the Bluetooth firmware directory. Flashing itself works the same way as on Android.
3. Flash, Then Bind
Flash the firmware, power-cycle the board, then bind it 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. If the list is empty, clear filters such as show unbound only and force a refresh. If it still will not appear, type the last eight characters of the Bluetooth MAC address directly into the MAC field.
Where does that MAC come from? An ESP32 board’s Bluetooth name is normally the last eight characters of its MAC, and the central control reads it automatically when binding a serial port. Label the board when it arrives, and label the matching phone too. With more than a handful of devices it saves real time.
After binding, the Bluetooth MAC column in the device list shows the hardware address. The mapping is UDID to Bluetooth MAC, one phone per board. That also explains the constraint: one board serves one phone at a time.
4. Test the Link Before Going Further
Binding only establishes the mapping. Whether the link actually carries data is separate, so test it.
On the phone, open Settings, go to Bluetooth, and pair with the board. The name is the last eight characters of the MAC, and the icon may appear as a keyboard or mouse.
Back in the central control, open Bluetooth HID settings and click test Bluetooth BLE. Leave the transport as serial, then click touch-and-hold or the HOME key.
If the phone responds, the whole path is working. If it does not, work through this order: forget the device on the phone and pair again, press reset on the board, then test once more.
5. Serial or WiFi
There are two transports between the board and the computer. Serial suits a board sitting next to the PC and needs no network setup. WiFi requires writing the network credentials into the board first, after which communication goes over the network.
The entry point is set WiFi information under Bluetooth HID settings. Restart the board afterward and the central control scans for its IP, which then appears in the hardware IP column.
Usually none of this needs manual intervention, because the central control scans automatically when it starts with correct bindings. Which one to pick depends on your rack layout: boards clustered near the PC suit serial, boards spread out next to devices suit WiFi.
6. Wrong Taps and Failed Connections
The Bluetooth path has its own class of problems, different from the cabled path.
Wrong tap positions come from three causes. The most common is a script that never calls the screen size setter: Bluetooth taps use absolute pixel coordinates, so without the width and height set first the math is off, and it has to be set again after any rotation change. The second is a wrong transport mode, such as a serial port already in use or network mode selected on a board that was never provisioned. The third is a bound MAC that does not belong to the board on the current serial port.
Failed connections have a routine too: hold reset on the board for about five seconds and release, then forget the device on the phone and search again. Remember that one board serves one phone, and the Bluetooth name may disappear once connected. Before rebinding, unpair and forget on the phone first, then press reset, then pair again.
The board’s LED tells you its state: solid for about three seconds after pairing then off, a slow blink of roughly ten after disconnecting, and a fast blink of roughly fifteen when searching.
One more thing people miss: the phone must complete pairing in Bluetooth settings and keep Bluetooth on. If the system asks to confirm a keyboard, mouse, or input device, allow it. USB debugging in Developer Options serves automation and screenshots, and it is not a substitute for the pairing.
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 on the EasyClick phone automation platform — full documentation, developer tools and cluster/cloud-control products, free to try.