tencent cloud

Feedback

Bluetooth - General

Last updated: 2024-07-16 18:03:27

    makeBluetoothPairstopBluetoothDevicesDiscovery

    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)
    
    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