tencent cloud

Feedback

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)
    }
    })
    
    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 avaliable.

    7x24 Phone Support