tencent cloud

All product documents
Tencent Cloud Super App as a Service
Bluetooth - General
Last updated: 2025-03-20 18:01:57
Bluetooth - General
Last updated: 2025-03-20 18:01:57

stopBluetoothDevicesDiscovery

This API is used via wx.stopBluetoothDevicesDiscovery(Object object).
Feature Description: Stops searching for nearby Bluetooth peripheral devices. It is advisable to invoke this interface to cease the Bluetooth search when the required Bluetooth device has been located and there is no need for further search.
Parameter and Description: Object.
Attribute
Type
Default value
Required
Description
success
function
-
No
Callback Function of Successful Interface Call
fail
function
-
No
Callback Function of Failing Interface Call
complete
function
-
No
Callback function executed upon the completion of the interface invocation (both successful and unsuccessful invocations)
Error Code
Error code
Error Message
Description
0
ok
Normal
-1
already connect
Connected
10000
not init
Bluetooth Adapter Not Initialized
10001
not available
The current Bluetooth adapter is unavailable.
10002
no device
Specified Device Not Found
10003
connection fail
Connection failed.
10004
no service
Specified Service Not Found
10005
no characteristic
Specified characteristic not found
10006
no connection
The current connection has been disconnected.
10007
property not support
The current characteristic does not support this operation.
10008
system error
Exceptions Reported by All Other Systems
10009
system not support
Exclusive to Android system, and BLE is not supported on versions earlier than 4.3.
10012
operate time out
Connection timeout
10013
invalid_data
The connection deviceId is either null or incorrectly formatted.
Sample Code
wx.stopBluetoothDevicesDiscovery({
success (res) {
console.log(res)
}
})

startBluetoothDevicesDiscovery

This API is used via wx.startBluetoothDevicesDiscovery(Object object).
Note:
Given that Bluetooth functionality can indirectly facilitate location tracking, Android 6.0 and later versions cannot perform device searches without location permissions or if the location switch is not activated. Under these circumstances, for versions prior to Android 8.0.16, the interface call will succeed but the device cannot be scanned; for Android 8.0.16 and later versions, an error prompt will be returned.
Feature Description: Starts the search for nearby Bluetooth peripheral devices. This operation is resource-intensive, hence it is advisable to promptly call wx.stopBluetoothDevicesDiscovery to stop the search once the required device has been found.
Parameter and Description: Object.
Attribute
Type
Default value
Required
Description
services
Array.<string>
-
No
The list of UUIDs for the primary services of the Bluetooth devices to be searched (supporting 16/32/128 bit UUIDs). Some Bluetooth devices will broadcast their primary service's UUID. If this parameter is set, only Bluetooth devices broadcasting a primary service with the corresponding UUID will be searched. It is recommended to use this parameter to filter out other surrounding Bluetooth devices that do not need to be processed.
allowDuplicatesKey
boolean
false
No
If or not allow to report the same device more than once. If repeat reporting is allowed, the wx.onBluetoothDeviceFound method will report the same device multiple times, but with different RSSI values.
interval
number
0
No
Interval for reporting devices, in ms. 0 means that new devices are found and reported immediately, other values are reported according to the incoming interval.
powerLevel
string
medium
No
The scanning mode. The higher the mode, the faster the scan and the greater the power consumption. Only Android host clients in V 7.0.12 and later versions support this, with valid values being:
Low: Low power
Medium: Moderate power
High: High power
success
function
-
No
Callback Function of Successful Interface Call
fail
function
-
No
Callback Function of Failing Interface Call
complete
function
-
No
Callback function executed upon the completion of the interface invocation (both successful and unsuccessful invocations)
Error Code
Error code
Error Message
Description
0
ok
Normal
-1
already connect
Connected
10000
not init
Bluetooth Adapter Not Initialized
10001
not available
The current Bluetooth adapter is unavailable.
10002
no device
Specified Device Not Found
10003
connection fail
Connection failed.
10004
no service
Specified Service Not Found
10005
no characteristic
Specified characteristic not found
10006
no connection
The current connection has been disconnected.
10007
property not support
The current characteristic does not support this operation.
10008
system error
Exceptions Reported by All Other Systems
10009
system not support
Exclusive to Android system, and BLE is not supported on versions earlier than 4.3.
10012
operate time out
Connection timeout
10013
invalid_data
The connection deviceId is either null or incorrectly formatted.
Sample Code
// Taking the Bluetooth smart light of the host client's hardware platform as an example, the UUID of the main service is FEE7. By passing in this parameter, only devices with a main service UUID of FEE7 will be searched for.
wx.startBluetoothDevicesDiscovery({
services: ['FEE7'],
success (res) {
console.log(res)
}
})

openBluetoothAdapter

This API is used via wx.openBluetoothAdapter(Object object).
Note:
Other Bluetooth-related APIs must be used after calling wx.openBluetoothAdapter. Otherwise, the API will return an error prompt (errCode=10000).
In situations where the user's Bluetooth switch is not turned on or the mobile phone does not support Bluetooth functionality, calling wx.openBluetoothAdapter will return an error code (errCode=10001), indicating that the mobile phone's Bluetooth functionality is unavailable.
Feature Description: Initializes the Bluetooth module. On iOS, when turning on the host/replica (peripheral) mode, it needs to be called once respectively, and the corresponding mode should be specified.
Parameter and Description: Object.
Attribute
Type
Valid Values and Descriptions
Default value
Required
Description
mode
string
central: Host mode
peripheral: Replica (peripheral device) mode
central
No
Bluetooth mode, which can function as a host/replica device, only required for iOS.
success
function
-
-
No
Callback Function of Successful Interface Call
fail
function
-
-
No
Callback Function of Failing Interface Call
complete
function
-
-
No
Callback function executed upon the completion of the interface invocation (both successful and unsuccessful invocations)
Error Return Value:
Error code
Error Message
Description
0
ok
Normal
-1
already connect
Connected
10000
not init
Bluetooth Adapter Not Initialized
10001
not available
The current Bluetooth adapter is unavailable.
10002
no device
Specified Device Not Found
10003
connection fail
Connection failed.
10004
no service
Specified Service Not Found
10005
no characteristic
Specified characteristic not found
10006
no connection
The current connection has been disconnected.
10007
property not support
The current characteristic does not support this operation.
10008
system error
Exceptions Reported by All Other Systems
10009
system not support
Exclusive to Android system, and BLE is not supported on versions earlier than 4.3.
10012
operate time out
Connection timeout
10013
invalid_data
The connection deviceId is either null or incorrectly formatted.
state parameter returned by the object.fail callback function (iOS only)
Status code
Description
0
Unknown
1
Resetting
2
Not supported
3
Not authorized
4
Not enabled
Sample Code
wx.openBluetoothAdapter({
success (res) {
console.log(res)
}
})

getConnectedBluetoothDevices

This API is used via wx.getConnectedBluetoothDevices(Object object).
Feature Description: Gets connected Bluetooth devices based on the primary service UUID.
Parameter and Description: Object.
Attribute
Type
Default value
Required
Description
services
Array.
-
Yes
List of primary service UUIDs for the Bluetooth device (supporting 16/32/128 bit UUIDs)
success
function
-
No
Callback Function of Successful Interface Call
fail
function
-
No
Callback Function of Failing Interface Call
complete
function
-
No
Callback function executed upon the completion of the interface invocation (both successful and unsuccessful invocations)
Object.success callback function: Object res.
Attribute
Type
Description
devices
Array.
List of located devices
Structure attributes
Type
Description
name
string
Bluetooth device name, which may not be available for some devices.
deviceId
string
Identifier used to distinguish devices
Error Return Value
Error code
Error Message
Description
0
ok
Normal
-1
already connect
Connected
10000
not init
Bluetooth Adapter Not Initialized
10001
not available
The current Bluetooth adapter is unavailable.
10002
no device
Specified Device Not Found
10003
connection fail
Connection failed.
10004
no service
Specified Service Not Found
10005
no characteristic
Specified characteristic not found
10006
no connection
The current connection has been disconnected.
10007
property not support
The current characteristic does not support this operation.
10008
system error
Exceptions Reported by All Other Systems
10009
system not support
Exclusive to Android system, and BLE is not supported on versions earlier than 4.3.
10012
operate time out
Connection timeout
10013
invalid_data
The connection deviceId is either null or incorrectly formatted.
Sample Code
wx.getConnectedBluetoothDevices({
services: ['FEE7'],
success (res) {
console.log(res)
}
})

getBluetoothDevices

This API is used via wx.getBluetoothDevices(Object object).
Note:
The device list obtained by this interface is all the searched Bluetooth devices during the effective period of the Bluetooth module, if you do not call wx.closeBluetoothAdapter to release the resources in time after the end of the Bluetooth module use process, there will be a call to this interface will return to the previous Bluetooth device searched in the Bluetooth use process, and the device may no longer be around the user and can not be connected.
Feature Description: Gets all Bluetooth devices detected during the effective period of the Bluetooth module, including devices already connected to this device.
Parameter and Description: Object.
Attribute
Type
Default value
Required
Description
success
function
-
No
Callback Function of Successful Interface Call
fail
function
-
No
Callback Function of Failing Interface Call
complete
function
-
No
Callback function executed upon the completion of the interface invocation (both successful and unsuccessful invocations)
Object.success callback function: Object res.
Attribute
Type
Description
devices
Array.<Object>
List of devices connected corresponding to the UUID
Structure attributes
Type
Description
name
string
Bluetooth device name, which may not be available for some devices.
deviceId
string
Bluetooth Device ID
RSSI
number
Signal strength of the current Bluetooth device, measured in dBm.
advertisData
ArrayBuffer
ManufacturerData segment in the broadcast data segment of the current Bluetooth device
advertisServiceUUIDs
Array.<string>
ServiceUUIDs data segment in the broadcast data segment of the current Bluetooth device
localName
string
LocalName data segment in the broadcast data segment of the current Bluetooth device
serviceData
Object
ServiceData segment in the broadcast data segment of the current Bluetooth device
connectable
boolean
Connectivity status of the current Bluetooth device (not supported on Android 8.0 and earlier Android versions)
Sample Code
// ArrayBuffer to 16 progress string example
function ab2hex(buffer) {
var hexArr = Array.prototype.map.call(
new Uint8Array(buffer),
function(bit) {
return ('00' + bit.toString(16)).slice(-2)
}
)
return hexArr.join('');
}
wx.getBluetoothDevices({
success: function (res) {
console.log(res)
if (res.devices[0]) {
console.log(ab2hex(res.devices[0].advertisData))
}
}
})

getBluetoothAdapterState

This API is used via wx.getBluetoothAdapterState(Object object).
Feature Description: Gets the status of the local Bluetooth adapter.
Parameter and Description: Object.
Attribute
Type
Default value
Required
Description
success
function
-
No
Callback Function of Successful Interface Call
fail
function
-
No
Callback Function of Failing Interface Call
complete
function
-
No
Callback function executed upon the completion of the interface invocation (both successful and unsuccessful invocations)
Object.success callback function: Object res.
Attribute
Type
Description
discovering
boolean
Is search for device in progress?
available
boolean
Whether the Bluetooth adapter is available.
Error Return Value
Error code
Error Message
Description
0
ok
Normal
-1
already connect
Connected
10000
not init
Bluetooth Adapter Not Initialized
10001
not available
The current Bluetooth adapter is unavailable.
10002
no device
Specified Device Not Found
10003
connection fail
Connection failed.
10004
no service
Specified Service Not Found
10005
no characteristic
Specified characteristic not found
10006
no connection
The current connection has been disconnected.
10007
property not support
The current characteristic does not support this operation.
10008
system error
Exceptions Reported by All Other Systems
10009
system not support
Exclusive to Android system, and BLE is not supported on versions earlier than 4.3.
10012
operate time out
Connection timeout
10013
invalid_data
The connection deviceId is either null or incorrectly formatted.
Sample Code
wx.getBluetoothAdapterState({
success (res) {
console.log(res)
}
})

closeBluetoothAdapter

This API is used via wx.closeBluetoothAdapter(Object object).
Feature Description: Disables the Bluetooth module. Invoking this method will disconnect all established connections and free up system resources. It is recommended to pair this with wx.openBluetoothAdapter after the Bluetooth process.
Parameter and Description: Object.
Attribute
Type
Default value
Required
Description
success
function
-
No
Callback Function of Successful Interface Call
fail
function
-
No
Callback Function of Failing Interface Call
complete
function
-
No
Callback function executed upon the completion of the interface invocation (both successful and unsuccessful invocations)
Error Return Value
Error code
Error Message
Description
0
ok
Normal
-1
already connect
Connected
10000
not init
Bluetooth Adapter Not Initialized
10001
not available
The current Bluetooth adapter is unavailable.
10002
no device
Specified Device Not Found
10003
connection fail
Connection failed.
10004
no service
Specified Service Not Found
10005
no characteristic
Specified characteristic not found
10006
no connection
The current connection has been disconnected.
10007
property not support
The current characteristic does not support this operation.
10008
system error
Exceptions Reported by All Other Systems
10009
system not support
Exclusive to Android system, and BLE is not supported on versions earlier than 4.3.
10012
operate time out
Connection timeout
10013
invalid_data
The connection deviceId is either null or incorrectly formatted.
Sample Code
wx.closeBluetoothAdapter({
success (res) {
console.log(res)
}
})

onBluetoothDeviceFound

This API is used via wx.onBluetoothDeviceFound(function listener).
Note:
If a device is called back in wx.onBluetoothDeviceFound, this device will be added to the array obtained by the wx.getBluetoothDevices interface.
When a Bluetooth device is discovered, the system generally returns the device name from the LocalName field in the broadcast packet as the name field. However, if a connection is established with the Bluetooth device, the system's name field will change to the GattName obtained from the Bluetooth device. If there is a need to dynamically change and display the device name, it is recommended to use the localName field.
Please note that some Android models require location permissions to search for devices. Ensure that location permissions are enabled.
Feature Description: Monitors events of finding new devices.
Parameter and Description: function listener, the listener function for events that search for new devices, with the arguments object res as follows:
Attribute
Type
Description
devices
Array.<Object>
List of newly located devices
Structure attribute of devices
Structure attributes
Type
Description
name
string
Bluetooth device name, which may not be available for some devices.
deviceId
string
Bluetooth Device ID
RSSI
number
Signal strength of the current Bluetooth device, measured in dBm.
advertisData
ArrayBuffer
ManufacturerData segment in the broadcast data segment of the current Bluetooth device
advertisServiceUUIDs
Array.<string>
ServiceUUIDs data segment in the broadcast data segment of the current Bluetooth device
localName
string
LocalName data segment in the broadcast data segment of the current Bluetooth device
serviceData
Object
ServiceData segment in the broadcast data segment of the current Bluetooth device
connectable
boolean
Connectivity status of the current Bluetooth device (not supported on Android 8.0 and earlier Android versions)
Sample Code
// Example of converting ArrayBuffer to hexadecimal string
function ab2hex(buffer) {
var hexArr = Array.prototype.map.call(
new Uint8Array(buffer),
function(bit) {
return ('00' + bit.toString(16)).slice(-2)
}
)
return hexArr.join('');
}
wx.onBluetoothDeviceFound(function(res) {
var devices = res.devices;
console.log('new device list has founded')
console.dir(devices)
console.log(ab2hex(devices[0].advertisData))
})

offBluetoothDeviceFound

This API is used via wx.offBluetoothDeviceFound()
Feature Description: Removes all listener functions for events of finding new devices.
Sample Code
wx.offBluetoothDeviceFound()

onBluetoothAdapterStateChange

This API is used via wx.onBluetoothAdapterStateChange(function listener).
Feature Description: Monitors events of Bluetooth adapter status changes.
Parameters and Description: Object res parameter, function listener, the listener function for events of changes to Bluetooth adapter status.
Attribute
Type
Description
available
boolean
Whether the Bluetooth adapter is available.
discovering
boolean
Whether the Bluetooth adapter is in search mode.
Sample Code
wx.onBluetoothAdapterStateChange(function (res) {
console.log('adapterState changed, now is', res)
})

offBluetoothAdapterStateChange

This API is used via wx.offBluetoothAdapterStateChange().
Feature Description: Removes all listener functions for events of changes to Bluetooth adapter status.
Sample Code
wx.offBluetoothAdapterStateChange()

makeBluetoothPair

This API is used via wx.makeBluetoothPair(Object object).
Feature Description: Bluetooth pairing interface, only supported by Android. Normally (when you need to specify a pin code or password) the system will take over the pairing process and call wx.createBLEConnection directly. This interface should only be used if the developer doesn't want the user to enter the pin code manually and the real phone verification confirms that it works.
Parameter and Description: Object
Attribute
Type
Default value
Required
Description
deviceId
string
-
Yes
Bluetooth Device ID
pin
string
-
Yes
Pin code, in Base64 format.
timeout
number
20000
No
Timeout duration, measured in milliseconds (ms).
success
function
-
No
Callback Function of Successful Interface Call
fail
function
-
No
Callback Function of Failing Interface Call
complete
function
-
No
Callback function executed upon the completion of the interface invocation (both successful and unsuccessful invocations)

isBluetoothDevicePaired

This API is used via wx.isBluetoothDevicePaired(Object object).
Feature Description: This function queries whether a Bluetooth device is paired, and is only supported on Android.
Parameter and Description: Object.
Attribute
Type
Default value
Required
Description
deviceId
string
-
Yes
Bluetooth Device ID
success
function
-
No
Callback Function of Successful Interface Call
fail
function
-
No
Callback Function of Failing Interface Call
complete
function
-
No
Callback function executed upon the completion of the interface invocation (both successful and unsuccessful invocations)

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback

Contact Us

Contact our sales team or business advisors to help your business.

Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 available.

7x24 Phone Support