Bluetooth API FAQ

Q: Does the API call of my. WriteBLECharacteristicValue return an empty value?

A: No. Calling this API returns the value of what you write.

Q: Why is listening not supported with the API call of my.onBLECharacteristicValueChange? Do I have to write before I can listen?

A: Yes. To call this API, you first need to write before you can listen. In order to prevent multiple callbacks of an event caused by multiple registered event listeners, it is recommended to call off method to listen to an event and close the previous event listener, before you call on method.

Q: Why do I get an error code 10014 with the API call of my. Why writeBLECharacteristicValue?

A: The error code 10014 means the data you send are either empty or incorrectly formatted. It is recommended to check for errors in the written data or HEX conversion.

Q: Can I use the hexadecimal array to write characteristic value with the API my writeBLECharacteristicValue ?

A: No. The characteristic values you write are hexadecimal strings, which are limited to 20 bytes.

Q: What is the deviceId format for Android and iOS devices?


  • An Android device gets the MAC address for bluetooth, such as: 11:22:33:44:55:66.
  • An iOS device gets the UUID of Bluetooth, such as: 00000000-0000-0000-0000-000000000000.

Q: Why can't I search for any device with the API call of my.startBluetoothDevicesDiscovery?

A: Please make sure that the device is discoverable. If the API is passed to Services, make sure that the discoverable content of the device contains the UUID of the service.

Q: If GPS positioning is not enabled when calling an bluetooth API, some devices will report an error message that bluetooth can't be connected as positioning service is not enabled.

A: The bluetooth function of the mini program relies on GPS positioning, as about 20% mobile phones rely on GPS to enable bluetooth. It is recommended to guide users to turn on the GPS positioning service in order to be connected with bluetooth.

Q: How do I resolve device connection failure?

A: Please make sure the correct deviceId is transmitted with strong signals. If the signal is weak, a device connection failure may occur.

Q: How to resolve write/read data failure?

A: Make sure to check the following settings:

  • DeviceId, serviceId, and characteristicId are transmitted in the correct format.
  • DeviceId is connected (You can call the API my. OnBLEConnectionStateChanged to listen to the connection state changes; Call the API my. GetConnectedBluetoothDevices to check for devices that are connected.
  • Write a method in the connected state.
  • Check and make sure characteristicId belongs to this Service.
  • This characteristic supports write/read.

Q: How do I receive data notifications?


  • Make sure to call the API my notifyBLECharacteristicValueChange with correct parameters.
  • Notify or indicate features are supported in the transmitted characteristicID.
  • Make sure the hardware is notified.
  • Pay attention to the basic flow sequence, i.e. call the API notifyBLECharacteristicValueChange once you're connected.

Q: Why are event callbacks called multiple times?

A: The same event was listened due to multiple anonymous function registrations. It is recommended to call off method to listen for an event and close the previous event listener, before you call on method.