tencent cloud

Tencent Cloud Super App as a Service

DocumentationTencent Cloud Super App as a ServiceMini Program Development GuideAPIDeviceBluetooth - Low Energy Peripheral Device

Bluetooth - Low Energy Peripheral Device

Download
Focus Mode
Font Size
Last updated: 2026-09-22 15:32:38
Note:
The APIs require the superapp to integrate the Bluetooth extension library. For integration instructions, see Extension SDK: Android | iOS

onBLEPeripheralConnectionStateChanged

This API is called using wx.onBLEPeripheralConnectionStateChanged(function listener).
Feature description:Listens for events when the current peripheral device is connected or disconnected.
Parameter and description:function listener: The listener function for the connection or disconnection events of the current peripheral device. The properties of Object res are as follows:
Property
Type
Note
deviceId
String
The ID of the device whose connection state changes.
serverId
String
The UUID of the server.
connected
Boolean
The current connection state.

offBLEPeripheralConnectionStateChanged

This API is called using wx.offBLEPeripheralConnectionStateChanged(function listener).
Feature description:Removes the listener for events when the current peripheral device is connected or disconnected.
Parameter and description:function listener: The listener function passed in onBLEPeripheralConnectionStateChanged. If not provided, all listeners will be removed.
Example:
const listener = function (res) { console.log(res) }

wx.onBLEPeripheralConnectionStateChanged(listener)
wx.offBLEPeripheralConnectionStateChanged(listener) // Must pass the same function object used in wx.onBLEPeripheralConnectionStateChanged(listener).

createBLEPeripheralServer

This API is called using wx.createBLEPeripheralServer(Object object).
Feature description:Establishes a local server as a Bluetooth Low Energy (BLE) peripheral server. You can create multiple servers.
Parameter and description:Object object.
Property
Type
Default value
‍Required
Description
success
function
-
False
Callback function for successful API calls.
fail
function
-
False
Callback function for failed API calls.
complete
function
-
False
Callback function executed after API call ends (regardless of success or failure).
object.success callback function parameter:Object res.
Property
Type
Description
Server
BLEPeripheralServer
The BLE peripheral server.

BLEPeripheralServer

Note:
The BLE peripheral server.

.addService

This API is called using BLEPeripheralServer.addService(Object object).
Feature description:Adds a service.
Parameter and description:Object object.
Property
Type
‍Required
Description
service
Object
Yes
The object describing the service.
success
function
No
Callback function for successful API calls.
fail
function
No
Callback function for failed API calls.
complete
function
No
Callback function executed after API call ends (regardless of success or failure).
Properties of service
Property
Type
‍Required
Description
uuid
string
Yes
The UUID of the Bluetooth service.
characteristics
Array.<Object>
Yes
The list of characteristics.
Properties of characteristics
Property
Type
‍Required
Description
uuid
string
Yes
The UUID of the characteristic.
properties
Object
No
The operations supported by the characteristic.
permission
Object
No
The permissions of the characteristic.
value
Array.<Object>
No
The binary value corresponding to the characteristic.
descriptors
Array.<Object>
No
The descriptor data.
Properties of properties
Property
Type
Default value
‍Required
Description
write
Boolean
false
No
Write.
writeNoResponse
Boolean
false
No
Write without response.
read
Boolean
false
No
Read.
notify
Boolean
false
No
Notify (Subscribe).
indicate
Boolean
false
No
Indicate (Response).
Properties of permission:
Property
Type
Default value
‍Required
Description
readable
Boolean
false
No
Readable.
writeable
Boolean
false
No
Writeable.
readEncryptionRequired
Boolean
false
No
Encrypted read request.
writeEncryptionRequired
Boolean
false
No
Encrypted write request.
Properties of descriptors
Property
Type
‍Required
Description
uuid
string
Yes
The UUID of the descriptor.
permission
Object
No
The permissions of the descriptor.
value
ArrayBuffer
No
The descriptor data.
Properties of permission:
Property
Type
Default value
‍Required
Description
write
Boolean
false
No
Write.
read
Boolean
false
No
Read.

.removeService

This API is called using BLEPeripheralServer.removeService(Object object).
Feature description:Removes a service.
Parameter and description:Object object.
Property
Type
Default value
‍Required
Description
serviceId
String
-
Yes
The UUID of the service.
success
function
-
No
Callback function for successful API calls.
fail
function
-
No
Callback function for failed API calls.
complete
function
-
No
Callback function executed after API call ends (regardless of success or failure).

.startAdvertising

This API is called using BLEPeripheralServer.startAdvertising(Object Object).
Feature description:Starts advertising the locally created peripheral device.
Parameter and description:Object object.
Property
Type
Default value
‍Required
Description
advertiseRequest
object
-
Yes
The custom advertising parameters.
powerLevel
string
medium
No
The advertising power. Valid values:
low: Low power;
medium: Medium power;
high: High power.
success
function
-
No
Callback function for successful API calls.
fail
function
-
No
Callback function for failed API calls.
complete
function
-
No
Callback function executed after API call ends (regardless of success or failure).
Properties of advertiseRequest
Property
Type
Default value
‍Required
Description
connectable
Boolean
true
No
Specifies whether the current device is connectable.
deviceName
string
-
No
The deviceName field in the broadcast. Defaults to empty.
serviceUuids
Array.<string>
-
No
The list of service UUIDs to advertise. See the notes when using 16-bit or 32-bit UUIDs.
manufactureData
Array.<Object>
-
No
The manufacturer data in the advertisement. Supported only on Android. iOS does not support customization due to system restrictions.
beacon
object
-
No
The parameters for advertising as a beacon device.
Properties of manufactureData
Property
Type
‍Required
Description
manufacturerId
String
Yes
The manufacturer ID in hexadecimal starting with 0x.
manufacturerSpecificData
ArrayBuffer
No
The manufacturer-specific data.
Properties of beacon
Property
Type
‍Required
Description
uuid
number
Yes
The UUID advertised by the beacon device.
major
number
Yes
The major ID of the beacon device.
minor
number
Yes
The minor ID of the beacon device.
measurePower
number
Yes
The reference value used to determine the RSSI when 1 meter away from the device.

.stopAdvertising

This API is called using BLEPeripheralServer.stopAdvertising().
Feature description:Stops advertising.
Parameter and description:Object object.
Property
Type
Default value
‍Required
Description
success
function
-
No
Callback function for successful API calls.
fail
function
-
No
Callback function for failed API calls.
complete
function
-
No
Callback function executed after API call ends (regardless of success or failure).

.writeCharacteristicValue

This API is called using BLEPeripheralServer.writeCharacteristicValue(Object Object).
Feature description:Writes a binary data value to a specified characteristic and notifies the connected central device. As the characteristic value of the peripheral has changed, this API handles whether to use indication (response) or notification (subscription).
Parameter and description:Object object.
Property
Type
Default value
‍Required
Description
serviceId
string
-
Yes
The UUID of the service corresponding to the Bluetooth characteristic.
characteristicId
string
-
Yes
The UUID of the Bluetooth characteristic.
value
ArrayBuffer
-
Yes
The binary value corresponding to the characteristic.
needNotify
Boolean
-
Yes
Specifies whether to notify the central device that the value has been updated.
callbackId
number
-
No
Optional. Used when processing indications (responses).
success
function
-
No
Callback function for successful API calls.
fail
function
-
No
Callback function for failed API calls.
complete
function
-
No
Callback function executed after API call ends (regardless of success or failure).

.onCharacteristicWriteRequest

This API is called using BLEPeripheralServer.onCharacteristicWriteRequest(function listener).
Feature description:Listens for the event when a connected device requests to write the characteristic value of the current peripheral device. Upon receiving this message, you must immediately call writeCharacteristicValue to write back data; otherwise, the central device will not receive a response.
Parameter and description:function listener, the listener function for events where a connected device requests to write the characteristic value of the current peripheral. The properties of Object res are as follows:
Property
Type
Description
serviceId
String
The UUID of the service corresponding to the Bluetooth characteristic.
characteristicId
String
The UUID of the Bluetooth characteristic.
callbackId
Number
The unique identifier used when calling  writeCharacteristicValue .
value
ArrayBuffer
The binary data value requested to be written to the characteristic.

.offCharacteristicWriteRequest

This API is called using BLEPeripheralServer.offCharacteristicWriteRequest(function listener).
Feature description:Removes the listener for the event when a connected device requests to write the characteristic value of the current peripheral device.
Parameter and description:function listener, the listener function passed in onCharacteristicWriteRequest. If not provided, all listeners will be removed.
Example:
const listener = function (res) { console.log(res) }

BLEPeripheralServer.onCharacteristicWriteRequest(listener)
BLEPeripheralServer.offCharacteristicWriteRequest(listener) // Must pass the same function object used in BLEPeripheralServer.onCharacteristicWriteRequest(listener).

.onCharacteristicReadRequest

This API is called using BLEPeripheralServer.onCharacteristicReadRequest(function listener).
Feature description:Listens for the event when a connected device requests to read the characteristic value of the current peripheral device. Upon receiving this message, you must immediately call writeCharacteristicValue to write back data; otherwise, the central device will not receive a response.
Parameter and description:function listener, the listener function for events where a connected device requests to read the characteristic value of the current peripheral. The properties of Object res are as follows:
Property
Type
Description
serviceId
String
The UUID of the service corresponding to the Bluetooth characteristic.
characteristicId
String
The UUID of the Bluetooth characteristic.
callbackId
Number
The unique identifier used when calling  writeCharacteristicValue .

.offCharacteristicReadRequest

This API is called using BLEPeripheralServer.offCharacteristicReadRequest(function listener).
Feature description:Removes the listener for the event when a connected device requests to read the characteristic value of the current peripheral device.
Parameter and description:function listener, the listener function passed in onCharacteristicReadRequest. If not provided, all listeners will be removed.
Example:
const listener = function (res) { console.log(res) }

BLEPeripheralServer.onCharacteristicReadRequest(listener)
BLEPeripheralServer.offCharacteristicReadRequest(listener) // Must pass the same function object used in BLEPeripheralServer.onCharacteristicReadRequest(listener).

.onCharacteristicSubscribed

This API is called using BLEPeripheralServer.onCharacteristicSubscribed(function listener).
Feature description:Listens for the characteristic subscription event (supported only on iOS).
Parameter and description:function listener, the listener function for characteristic subscription events. See the parameter Object.res as below.
Property
Type
Description
serviceId
String
The UUID of the service corresponding to the Bluetooth characteristic.
characteristicId
String
The UUID of the Bluetooth characteristic.

.offCharacteristicSubscribed

This API is called using BLEPeripheralServer.offCharacteristicSubscribed(function listener).
Feature description:Removes the listener for the characteristic subscription event (supported only on iOS).
Parameter and description:function listener, the listener function passed in onCharacteristicSubscribed. If not provided, all listeners will be removed.
Example:
const listener = function (res) { console.log(res) }

BLEPeripheralServer.onCharacteristicSubscribed(listener)
BLEPeripheralServer.offCharacteristicSubscribed(listener) // Must pass the same function object used in BLEPeripheralServer.onCharacteristicSubscribed(listener).

.onCharacteristicUnsubscribed

This API is called using BLEPeripheralServer.onCharacteristicUnsubscribed(function listener).
Feature description:Listens for the characteristic unsubscription event (supported only on iOS).
Parameter and description:function listener, the listener function for characteristic unsubscription events. See the parameter Object.res as below.
Property
Type
Description
serviceId
String
The UUID of the service corresponding to the Bluetooth characteristic.
characteristicId
String
The UUID of the Bluetooth characteristic.

.offCharacteristicUnsubscribed

This API is called using BLEPeripheralServer.offCharacteristicUnsubscribed(function listener).
Feature description:Removes the listener for the characteristic unsubscription event (supported only on iOS).
Parameter and description:function listener, the listener function passed in onCharacteristicUnsubscribed. If not provided, all listeners will be removed.
Example:
const listener = function (res) { console.log(res) }

BLEPeripheralServer.onCharacteristicUnsubscribed(listener)



Previous Topic: Bluetooth - Low Energy Central DeviceNext Topic: Bluetooth - Beacon

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback

Search
    Enter keywords to search documentation