tencent cloud

All product documents
Tencent Cloud Super App as a Service
Bluetooth - Low Energy Central Device
Last updated: 2024-11-21 18:48:12
Bluetooth - Low Energy Central Device
Last updated: 2024-11-21 18:48:12

writeBLECharacteristicValue

This API is used via wx.writeBLECharacteristicValue(Object object).
Note:
Simultaneous multiple calls may potentially result in write failures.
While the mini program does not impose restrictions on the size of the data packet written, the system and Bluetooth device will limit the data size of a single Bluetooth 4.0 transmission. Since exceeding the maximum byte count may result in write errors, it is recommended not to exceed 20 bytes per write operation.
If data is written in a single instance that is excessively long, iOS may not provide any callbacks, including error callbacks.
On the Android platform, invoking this interface immediately after successfully calling wx.notifyBLECharacteristicValueChange may result in a system error coded 10008 on certain models.
Feature Description: Writes binary data into the characteristic value of a low-energy Bluetooth device. Successful invocation requires the device's characteristic to support write operations.
Parameter and Description: Object.
Attribute
Type
Required
Description
deviceId
string
Yes
Bluetooth Device ID
serviceId
string
Yes
UUID corresponding to the Bluetooth characteristic service
characteristicId
string
Yes
Bluetooth characteristic UUID
value
ArrayBuffer
Yes
The binary data of the characteristic value from the Bluetooth device.
writeType
string
No
Write mode setting for Bluetooth feature value, there are two modes, iOS priority write and Android priority writeNoResponse. legal value is:
write: Mandatory write response, reporting error when unsupported.
'writeNoResponse': Mandatory write without response, reporting error when unsupported.
success
function
No
Callback Function of Successful Interface Call
fail
function
No
Callback Function of Successful 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
// Transmit a hexadecimal data of 0x00 to the Bluetooth device.
let buffer = new ArrayBuffer(1)
let dataView = new DataView(buffer)
dataView.setUint8(0, 0)

wx.writeBLECharacteristicValue({
// The deviceId here must be obtained through the getBluetoothDevices or onBluetoothDeviceFound interfaces.
deviceId,
// The ServiceId here must be obtained from the wx.getBLEDeviceServices interface.
serviceId,
// The CharacteristicId Here must be obtained from the getBLEDeviceCharacteristics interface.
characteristicId,
// The value here is of ArrayBuffer type.
value: buffer,
success (res) {
console.log('writeBLECharacteristicValue success', res.errMsg)
}
})

readBLECharacteristicValue

This API is used via wx.readBLECharacteristicValue(Object object).
Note:
Simultaneous multiple calls may potentially result in read failures.
The Information read from the interface must be obtained in the callback registered by the wx.onBLECharacteristicValueChange method.
Feature Description: Reads the binary data of the low-energy Bluetooth device characteristics. Successful invocation is only possible if the device's characteristic supports read.
Parameter and Description: Object.
Attribute
Type
Default value
Required
Description
deviceId
string
-
Yes
Bluetooth Device ID
serviceId
string
-
Yes
UUID corresponding to the Bluetooth characteristic service
characteristicId
string
-
Yes
Bluetooth characteristic UUID
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
// Retrieval is only possible in this callback.
wx.onBLECharacteristicValueChange(function(characteristic) {
console.log('characteristic value comed:', characteristic)
})

wx.readBLECharacteristicValue({
// The deviceId here must have already established a link with the corresponding device through createBLEConnection.
deviceId,
// The ServiceId here must be obtained from the wx.getBLEDeviceServices interface.
serviceId,
// The CharacteristicId Here Must be Retrieved from the getBLEDeviceCharacteristics Interface
characteristicId,
success (res) {
console.log('readBLECharacteristicValue:', res.errCode)
}
})

setBLEMTU

This API is used via wx.setBLEMTU(Object object).
Feature Description: Negotiates the setting of the maximum transmission unit (MTU) for low-energy Bluetooth devices. It needs to be called after wx.createBLEConnection has been successfully invoked. This is only effective on Android systems version 5.1 and later versions, and is not supported on iOS due to system limitations.
Parameter and Description: Object.
Attribute
Type
Default value
Required
Description
deviceId
string
-
Yes
Bluetooth Device ID
mtu
number
-
Yes
Maximum Transmission Unit. The setting range is within the interval (22,512), measured in bytes.
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)
Parameters for object.success callback function: Object res.
Attribute
Type
Description
mtu
number
The final negotiated MTU value, which is consistent with the parameter passed in. It is supported from Android client 8.0.9 onwards.

getBLEMTU

This API is used via wx.getBLEMTU(Object object).
Note:
Within the mini program, the MTU is ATT_MTU, which includes the length of the Op-Code and Attribute Handle. The actual data transmission length is ATT_MTU - 3.
In the iOS system, the MTU is a fixed value; in the Android system, the MTU changes after successful system negotiation. It is recommended to use wx.onBLEMTUChange for monitoring.
Feature Description: Gets the maximum transmission unit of low-energy Bluetooth devices. It needs to be called after wx.createBLEConnection has been successfully invoked.
Parameter and Description: Object.
Attribute
Type
Default value
Required
Description
deviceId
string
-
Yes
Bluetooth Device ID
writeType
string
write
No
Write mode (specific to iOS). Valid values are:
write: Write with response.
writeNoResponse: Write without response.
success
function
-
No
Callback Function of Successful Interface Call
fail
function
-
No
Callback Function of Successful Interface Call
complete
function
-
No
Callback function executed upon the completion of the interface invocation (both successful and unsuccessful invocations)
Parameters for object.success callback function: Object res.
Attribute
Type
Description
mtu
number
Maximum Transmission Unit
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.getBLEMTU({
deviceId: '',
writeType: 'write',
success (res) {
console.log(res)
}
})

onBLEMTUChange

This API is used via wx.onBLEMTUChange(function listener).
Feature Description: Monitors events of MTU changes in low-energy Bluetooth devices (only triggered on Android).
Parameter and Description: Object res parameter, function listener, the listener function for events of MTU changes in low-energy Bluetooth devices.
Attribute
Type
Description
deviceId
string
Bluetooth Device ID
mtu
number
Maximum Transmission Unit
Sample Code
wx.onBLEMTUChange(function (res) {
console.log('bluetooth mtu is', res.mtu)
})

offBLEMTUChange

This method is used via wx.offBLEMTUChange(function listener).
Feature Description: Removes the listener function for events of MTU changes in low-energy Bluetooth devices.
Parameter and Description: function listener, the listener function passed in by onBLEMTUChange. If this parameter is not passed in, all listener functions will be removed.
Sample Code
const listener = function (res) { console.log(res) }

wx.onBLEMTUChange(listener)
wx.offBLEMTUChange(listener) // The same function object as the listener must be passed in.

onBLEConnectionStateChange

This API is used via wx.onBLEConnectionStateChange(function listener).
Feature Description: Monitors events of changes to low-energy Bluetooth connection status. This includes active connections or disconnections by developers, device loss, exceptional disconnections, and so on.
Parameters and Description: function listener, the Bluetooth low power connection state change event listener function, the parameter Object res is as follows:
Attribute
Type
Description
deviceId
string
Bluetooth Device ID
connected
boolean
Whether it is in connected status.
Sample Code
wx.onBLEConnectionStateChange(function(res) {
// This method callback can be used to handle exceptional situations such as unexpected disconnections.
console.log(device ${res.deviceId} state has changed, connected: ${res.connected})
})

offBLEConnectionStateChange

This API is used via wx.offBLEConnectionStateChange(function listener).
Feature Description: Removes the listener function for events of changes to low-energy Bluetooth connection status.
Parameter and Description: function listener, the listener function passed in by onBLEConnectionStateChange. If this parameter is not passed in, all listener functions will be removed.
Sample Code
const listener = function (res) { console.log(res) }

wx.onBLEConnectionStateChange(listener)
wx.offBLEConnectionStateChange(listener) // The same function object as the listener must be passed in.

onBLECharacteristicValueChange

This API is used via wx.onBLECharacteristicValueChange(function listener).
Feature Description: Monitors events of characteristic value changes for low-energy Bluetooth devices. You must first call the wx.notifyBLECharacteristicValueChange interface to receive notifications pushed by the device.
Parameter and Description: function listener, the listener function for the feature value change event of the Bluetooth low power device, with the following parameters Object res:
Attribute
Type
Description
deviceId
string
Bluetooth Device ID
serviceId
string
UUID corresponding to the Bluetooth characteristic service
characteristicId
string
Bluetooth characteristic UUID
value
ArrayBuffer
The latest characteristic value
Sample Code
// Example of converting ArrayBuffer to hexadecimal string
function ab2hex(buffer) {
let hexArr = Array.prototype.map.call(
new Uint8Array(buffer),
function(bit) {
return ('00' + bit.toString(16)).slice(-2)
}
)
return hexArr.join('');
}
wx.onBLECharacteristicValueChange(function(res) {
console.log(characteristic ${res.characteristicId} has changed, now is ${res.value})
console.log(ab2hex(res.value))
})

offBLECharacteristicValueChange

This API is used via wx.offBLECharacteristicValueChange().
Feature Description: Removes all listener functions for events of characteristic value changes for low-energy Bluetooth devices.
Sample Code
wx.offBLECharacteristicValueChange()

notifyBLECharacteristicValueChange

This API is used via wx.notifyBLECharacteristicValueChange(Object object).
Note:
After the subscription operation is successful, the device needs to actively update the characteristic value to trigger the wx.onBLECharacteristicValueChange callback.
On the Android platform, invoking the wx.writeBLECharacteristicValue interface immediately after successfully calling this interface may result in a system error coded 10008 on certain models.
The device's characteristic must support "notify" or "indicate" for the call to be successful. Additionally, wx.notifyBLECharacteristicValueChange must be enabled first to monitor the device's characteristicValueChange event.
Feature Description: Enables the "notify" feature when the characteristic value of low-energy Bluetooth device changes, subscribing to the characteristics.
Parameter and Description: Object.
Attribute
Type
Default value
Required
Description
deviceId
string
-
Yes
Bluetooth Device ID
serviceId
string
-
Yes
UUID corresponding to the Bluetooth characteristic service
characteristicId
string
-
Yes
Bluetooth characteristic UUID
state
boolean
-
Yes
Whether to enable "notify"
type
string
indication
No
Set the characteristic subscription type, whose valid values include "notification" and "indication".
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
// Transmit a hexadecimal data of 0x00 to the Bluetooth device.
let buffer = new ArrayBuffer(1)
let dataView = new DataView(buffer)
dataView.setUint8(0, 0)

wx.writeBLECharacteristicValue({
// The deviceId here must be obtained through the getBluetoothDevices or onBluetoothDeviceFound interfaces.
deviceId,
// The ServiceId here must be obtained from the wx.getBLEDeviceServices interface.
serviceId,
// The CharacteristicId Here Must be Retrieved from the getBLEDeviceCharacteristics Interface
characteristicId,
// The Value Here is of ArrayBuffer Type
value: buffer,
success (res) {
console.log('writeBLECharacteristicValue success', res.errMsg)
}
})

getBLEDeviceServices

This API is used via wx.getBLEDeviceServices(Object object).
Feature Description: Gets all services from the low-energy Bluetooth device.
Parameter and Description: Object.
Attribute
Type
Default value
Required
Description
deviceId
string
-
Yes
Bluetooth device id. A connection must have already been established through wx.createBLEConnection.
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)
Parameters for object.success callback function: Object res.
Attribute
Type
Description
services
Array.<Object>
Device service list
Structure attribute of service
Attribute
Type
Description
uuid
string
Bluetooth device service UUID
isPrimary
boolean
Whether the service is a primary service.
Sample Code
wx.getBLEDeviceServices({
// The deviceId here must have already established a link with the corresponding device through wx.createBLEConnection.
deviceId,
success (res) {
console.log('device services:', res.services)
}
})

getBLEDeviceRSSI

This API is used via wx.getBLEDeviceRSSI(Object object).
Feature Description: Gets the signal strength (Received Signal Strength Indication, RSSI) of the low-energy Bluetooth device.
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)
Parameters for object.success callback function: Object res.
Attribute
Type
Description
RSSI
Number
Signal strength, measured in dBm

getBLEDeviceCharacteristics

This API is used via wx.getBLEDeviceCharacteristics(Object object).
Feature Description: Gets all characteristics within a service from a low-energy Bluetooth device.
Parameter and Description: Object.
Attribute
Type
Default value
Required
Description
deviceId
string
-
Yes
Bluetooth device id. A connection must have already been established through wx.createBLEConnection.
serviceId
string
-
Yes
Bluetooth service UUID. It is necessary to first invoke wx.getBLEDeviceServices to get it.
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)
Parameters for object.success callback function: Object res.
Attribute
Type
Description
characteristics
Array.<Object>
Device characteristic value list
Structure attributes of characteristics
Structure attributes
Type
Description
uuid
string
Bluetooth device characteristic UUID
properties
Object
Operation types supported by this characteristic
Structure attributes of properties
Attribute
Type
Description
read
boolean
Whether this characteristic supports the read operation.
write
boolean
Whether this characteristic supports the write operation.
notify
boolean
Whether this characteristic supports the notify operation.
indicate
boolean
Whether this characteristic supports the indicate operation.
writeNoResponse
boolean
Whether this characteristic supports the writeNoResponse operation.
writeDefault
boolean
Whether this characteristic supports the writeDefault operation.
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.getBLEDeviceCharacteristics({
// The deviceId here needs to have already established a link with the corresponding device through wx.createBLEConnection
deviceId,
// The ServiceId here must be obtained from the wx.getBLEDeviceServices interface.
serviceId,
success (res) {
console.log('device getBLEDeviceCharacteristics:', res.characteristics)
}
})

createBLEConnection

This API is used via wx.createBLEConnection(Object object).
Note:
Please ensure to pair the calls to wx.createBLEConnection and wx.closeBLEConnection interfaces as much as possible. On Android, if wx.createBLEConnection is repeatedly called to create a connection, it may cause the system to hold multiple connection instances of the same device, resulting in the inability to truly disconnect from the device when calling closeBLEConnection.
The Bluetooth connection may disconnect at any time. It is recommended to monitor wx.onBLEConnectionStateChange callback events and perform reconnection operations as needed when the Bluetooth device is disconnected.
If data read and write operation interfaces are called on unconnected devices or devices that have disconnected, an error coded 10006 will be returned. It is recommended to perform reconnection operations.
Feature Description: Connects to a low-energy Bluetooth device. If the mini program has previously searched for a certain Bluetooth device and successfully established a connection, you can directly pass in the deviceId obtained from the previous search to attempt to connect to the device, eliminating the need for another search operation.
Parameter and Description: Object.
Attribute
Type
Default value
Required
Description
deviceId
string
-
Yes
Bluetooth Device ID
timeout
number
-
No
Timeout period, in milliseconds (ms). If left blank, it indicates that there will be no timeout.
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.createBLEConnection({
deviceId,
success (res) {
console.log(res)
}
})

closeBLEConnection

This API is used wx.closeBLEConnection(Object object).
Feature Description: Disconnects from the low-energy Bluetooth device.
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)
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.closeBLEConnection({
deviceId,
success (res) {
console.log(res)
}
})

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