WeChat Open Platform

Mini Programs Documentation

Bluetooth adapter interface

Support for base library version 1.1.0 has begun, earlier versions require compatibility processing.

iOS Wechat client version 6.5.6 and Android version 6.5.7 have begun support.

wx.openBluetoothAdapter(OBJECT)

Initializes Bluetooth adapter

OBJECT parameter descriptions:

Parameter Type Required Description
success Function Yes A successful initialization message will be returned if successful
fail Function No Callback function for failed interface call
complete Function No Callback function for interface call results (will be executed if call succeeds or fails)

Sample code:

wx.openBluetoothAdapter({
  success: function (res) {
    console.log(res)
  }
})

Bugs & Tips

  1. tip: Due to system problems, Bluetooth debugging is currently only supported on Mac version developer tools.
  2. tip: Support for base library version 1.1.0 has begun, earlier versions require compatibility processing.

wx.closeBluetoothAdapter(OBJECT)

Closes Bluetooth module. Calling this method will break all created links and free up system resources.

OBJECT parameter descriptions:

Parameter Type Required Description
success Function Yes A module closed successfully message will be returned if successful
fail Function No Callback function for failed interface call
complete Function No Callback function for interface call results (will be executed if call succeeds or fails)

Sample code:

wx.closeBluetoothAdapter({
  success: function (res) {
    console.log(res)
  }
})

wx.getBluetoothAdapterState(OBJECT)

Gets local Bluetooth adapter state.

OBJECT parameter descriptions:

Parameter Type Required Description
success Function Yes Returns local Bluetooth adapter state if successful
fail Function No Callback function for failed interface call
complete Function No Callback function for interface call results (will be executed if call succeeds or fails)

success return parameters:

Parameter Type Description
adapterState object Bluetooth adapter information
errMsg string Success: ok; error: detailed information

adapterState

Bluetooth adapter state information

Parameter Type Description
discovering boolean Whether searching for device
available boolean Whether Bluetooth adapter is available

Sample code:

wx.getBluetoothAdapterState({
  success: function (res) {
    console.log(res)
  }
})

wx.onBluetoothAdapterStateChange(CALLBACK)

Monitors Bluetooth adapter state change events.

CALLBACK parameter descriptions:

Parameter Type Description
available boolean Whether Bluetooth adapter is available
discovering boolean Whether Bluetooth adapter is in search mode

Sample code:

wx.onBluetoothAdapterStateChange(function(res) {
  console.log(`adapterState changed, now is`, res)
})

wx.startBluetoothDevicesDiscovery(OBJECT)

Starts searching for nearby Bluetooth peripheral devices. Note that this action uses up quite a lot of system resources. Please call the stop method to stop searching after searching for and connecting to a device.

OBJECT parameter descriptions:

Parameter Type Required Description
services Array No Bluetooth device primary service UUID list
success Function Yes Returns local Bluetooth adapter state if successful
fail Function No Callback function for failed interface call
complete Function No Callback function for interface call results (will be executed if call succeeds or fails)

Services parameter description: some Bluetooth devices will broadcast their own primary service UUIDs. If this array is imported here, then only devices that have this primary service will be searched for, in accordance with the UUID list.

success return parameters:

Parameter Type Description
errMsg string Success: ok; error: detailed information

Sample code:

// Using the WeChat hardware platform's Bluetooth smart lamp as an example, its primary service UUID is FEE7 Only search for devices whose primary service UUID is FEE7 when importing this parameter
wx.startBluetoothDevicesDiscovery({
  services: ['FEE7'],
  success: function (res) {
    console.log(res)
  }
})

wx.stopBluetoothDevicesDiscovery(OBJECT)

Stops searching for nearby Bluetooth peripheral devices. Please call this method to stop searching after ensuring that you have found the device you want to connect to.

OBJECT parameter descriptions:

Parameter Type Required Description
success Function Yes Returns local Bluetooth adapter state if successful
fail Function No Callback function for failed interface call
complete Function No Callback function for interface call results (will be executed if call succeeds or fails)

success return parameters:

Parameter Type Description
errMsg string Success: ok; error: detailed information

adapterState

Bluetooth adapter state information

Parameter Type Description
discovering boolean Whether searching for device
available boolean Whether Bluetooth adapter is available

Sample code:

wx.stopBluetoothDevicesDiscovery({
  success: function (res) {
    console.log(res)
  }
})

wx.getBluetoothDevices(OBJECT)

Gets all Bluetooth devices that have been found, including devices that are already connected to your machine.

OBJECT parameter descriptions:

Parameter Type Required Description
services Array No Bluetooth device primary service UUID list
success Function Yes Returns local Bluetooth adapter state if successful
fail Function No Callback function for failed interface call
complete Function No Callback function for interface call results (will be executed if call succeeds or fails)

success return parameters:

Parameter Type Description
devices Array List of connected devices corresponding to UUIDs
errMsg string Success: ok; error: detailed information

device objects

Bluetooth device information

Parameter Type Description
name string Bluetooth device name, some devices may not have one
deviceId string id used to distinguish between devices
RSSI int Current Bluetooth device signal strength
advertisData ArrayBuffer Broadcast content of current Bluetooth device

Sample code:

wx.getBluetoothDevices({
  success: function (res) {
    console.log(res)
  }
})

Bugs & Tips

  1. tip: Mac systems may be unable to get advertisData or RSSI, please use real machine debugging.
  2. tip: deviceIds obtained in Developer Tools and Android are device MAC addresses. On iOS these are device UUIDs. deviceIds therefore cannot be hard coded into code.

wx.onBluetoothDeviceFound(CALLBACK)

Monitors events for new devices that are searched for.

CALLBACK parameter descriptions:

Parameter Type Description
devices Array List of newly searched for devices

device objects

Parameter Type Description
deviceId string Bluetooth device id, reference device object
name string Bluetooth device name, reference device object
RSSI int Current Bluetooth device signal strength
advertisData ArrayBuffer Broadcast content of current Bluetooth device

Sample code:

wx.onBluetoothDeviceFound(function(devices) {
  console.log('new device list has founded')
  console.dir(devices)
})

Bugs & Tips

  1. tip: Mac systems may be unable to get advertisData or RSSI, please use real machine debugging.
  2. tip: deviceIds obtained in Developer Tools and Android are device MAC addresses. On iOS these are device UUIDs. deviceIds therefore cannot be hard coded into code.

wx.getConnectedBluetoothDevices(OBJECT)

Gets connected devices according to UUID.

OBJECT parameter descriptions:

Parameter Type Required Description
services Array Yes Bluetooth device primary service UUID list
success Function Yes Returns local Bluetooth adapter state if successful
fail Function No Callback function for failed interface call
complete Function No Callback function for interface call results (will be executed if call succeeds or fails)

success return parameters:

Parameter Type Description
devices Array List of devices searched for
errMsg string Success: ok; error: detailed information

device objects

Bluetooth device information

Parameter Type Description
name string Bluetooth device name, some devices may not have one
deviceId string id used to distinguish between devices

Sample code:

wx.getConnectedBluetoothDevices({
  success: function (res) {
    console.log(res)
  }
})

Bugs & Tips

  1. tip: deviceIds obtained in Developer Tools and Android are device MAC addresses. On iOS these are device UUIDs. deviceIds therefore cannot be hard coded into code.

Low power Bluetooth interface

wx.createBLEConnection(OBJECT)

Connects low power Bluetooth devices.

OBJECT parameter descriptions:

Parameter Type Required Description
deviceId string Yes Bluetooth device id, refer to getDevices interface
success Function Yes Returns local Bluetooth adapter state if successful
fail Function No Callback function for failed interface call
complete Function No Callback function for interface call results (will be executed if call succeeds or fails)

success return parameters:

Parameter Type Description
errMsg string Success: ok; error: detailed information

Sample code:

wx.createBLEConnection({
  // The deviceId here needs to be obtained from the getBluetoothDevices or onBluetoothDeviceFound interface above
  deviceId: deviceId,
  success: function (res) {
    console.log(res)
  }
})

wx.closeBLEConnection(OBJECT)

Disconnects low power Bluetooth devices.

OBJECT parameter descriptions:

Parameter Type Required Description
deviceId string Yes Bluetooth device id, refer to getDevices interface
success Function Yes Returns local Bluetooth adapter state if successful
fail Function No Callback function for failed interface call
complete Function No Callback function for interface call results (will be executed if call succeeds or fails)

success return parameters:

Parameter Type Description
errMsg string Success: ok; error: detailed information

Sample code:

wx.closeBLEConnection({
  success: function (res) {
    console.log(res)
  }
})

wx.getBLEDeviceServices(OBJECT)

Gets all Bluetooth device services.

OBJECT parameter descriptions:

Parameter Type Required Description
deviceId string Yes Bluetooth device id, refer to getDevices interface
success Function Yes Returns local Bluetooth adapter state if successful
fail Function No Callback function for failed interface call
complete Function No Callback function for interface call results (will be executed if call succeeds or fails)

success return parameters:

Parameter Type Description
services array Device service list
errMsg string Success: ok; error: detailed information

service objects

Bluetooth device service information

Parameter Type Description
UUID string Bluetooth device service UUID
isPrimary boolean Whether this service is a primary service

Sample code:

wx.getBLEDeviceServices({
  // The deviceId here needs to be obtained from the getBluetoothDevices or onBluetoothDeviceFound interface above
  deviceId: deviceId,
  success: function (res) {
    console.log('device services:', res.services)
  }
})

wx.getBLEDeviceCharacteristics(OBJECT)

Gets all Bluetooth device characteristics (characteristic values).

OBJECT parameter descriptions:

Parameter Type Required Description
deviceId string Yes Bluetooth device id, reference device object
serviceId string Yes Bluetooth service UUID
success Function Yes Returns local Bluetooth adapter state if successful
fail Function No Callback function for failed interface call
complete Function No Callback function for interface call results (will be executed if call succeeds or fails)

success return parameters:

Parameter Type Description
characteristics array Device characteristic value list
errMsg string Success: ok; error: detailed information

characteristic objects

Bluetooth device characteristic (characteristic value) information

Parameter Type Description
UUID string Bluetooth device characteristic value UUID
properties object The action types supported by this characteristic value
properties objects
Parameter Type Description
read boolean Whether this characteristic value supports read actions
write boolean Whether this characteristic value supports write actions
notify boolean Whether this characteristic value supports notify actions
indicate boolean Whether this characteristic value supports indicate actions

Sample code:

wx.getBLEDeviceCharacteristics({
  // The deviceId here needs to be obtained from the getBluetoothDevices or onBluetoothDeviceFound interface above
  deviceId: deviceId,
  // The serviceId here needs to be obtained from the getBLEDeviceServices interface above
  serviceId: serviceId,
  success: function (res) {
    console.log('device getBLEDeviceCharacteristics:', res.characteristics)
  }
})

wx.readBLECharacteristicValue(OBJECT)

Reads binary data values for low power Bluetooth device characteristic values. Note: Device characteristic values must support read before they can be called successfully, this specifically refers to the properties attributes of characteristics.

OBJECT parameter descriptions:

Parameter Type Required Description
deviceId string Yes Bluetooth device id, reference device object
serviceId string Yes Corresponding service UUID for Bluetooth characteristic value
characteristicId string Yes Bluetooth characteristic value UUID
success Function Yes Returns local Bluetooth adapter state if successful
fail Function No Callback function for failed interface call
complete Function No Callback function for interface call results (will be executed if call succeeds or fails)

success return parameters:

Parameter Type Description
characteristic object Device characteristic value information
errMsg string Success: ok; error: detailed information

characteristic objects

Bluetooth device characteristic (characteristic value) information

Parameter Type Description
characteristicId string Bluetooth device characteristic value UUID
serviceId object Corresponding service UUID for Bluetooth device characteristic value
value ArrayBuffer Corresponding binary value for Bluetooth device characteristic value

Sample code:

// Must only be obtained at the call back here
wx.onBLECharacteristicValueChange(function(characteristic) {
  console.log('characteristic value comed:', characteristic)
})

wx.readBLECharacteristicValue({
  // The deviceId here needs to be obtained from the getBluetoothDevices or onBluetoothDeviceFound interface above
  deviceId: deviceId,
  // The serviceId here needs to be obtained from the getBLEDeviceServices interface above
  serviceId: serviceId,
  // The characteristicId here needs to be obtained from the getBLEDeviceCharacteristics interface above
  characteristicId: characteristicId,
  success: function (res) {
    console.log('readBLECharacteristicValue:', res.characteristic.value)
  }
})

Bugs & Tips

  1. tip: There is a possibility of read and write failures when concurrently calling multiple read and write interfaces.
  2. tip: The information read by the read interface needs to be obtained from the callback registered by the onBLECharacteristicValueChange method.

wx.writeBLECharacteristicValue(OBJECT)

Writes binary data for low power Bluetooth device characteristic values. Note: Device characteristic values must support write before they can be called successfully, this specifically refers to the properties attributes of characteristics.

tips: There is a possibility of read and write failures when concurrently calling multiple read and write interfaces.

OBJECT parameter descriptions:

Parameter Type Required Description
deviceId string Yes Bluetooth device id, reference device object
serviceId string Yes Corresponding service UUID for Bluetooth characteristic value
characteristicId string Yes Bluetooth characteristic value UUID
value ArrayBuffer Yes Corresponding binary value for Bluetooth device characteristic value
success Function Yes Returns local Bluetooth adapter state if successful
fail Function No Callback function for failed interface call
complete Function No Callback function for interface call results (will be executed if call succeeds or fails)

success return parameters:

Parameter Type Description
errMsg string Success: ok; error: detailed information

Sample code:

// The callback here can get characteristic value changes caused by write
wx.onBLECharacteristicValueChange(function(characteristic) {
  console.log('characteristic value changed:', characteristic)
})

// Send 0x00 hexadecimal data to Bluetooth device
let buffer = new ArrayBuffer(1)
let dataView = new DataView(buffer)
dataView.setUint8(0, 0)

wx.writeBLECharacteristicValue({
  // The deviceId here needs to be obtained from the getBluetoothDevices or onBluetoothDeviceFound interface above
  deviceId: deviceId,
  // The serviceId here needs to be obtained from the getBLEDeviceServices interface above
  serviceId: serviceId,
  // The characteristicId here needs to be obtained from the getBLEDeviceCharacteristics interface above
  characteristicId: characteristicId,
  // The value here is ArrayBuffer type
  value: buffer,
  success: function (res) {
    console.log('writeBLECharacteristicValue success', res.errMsg)
  }
})

wx.notifyBLECharacteristicValueChange(OBJECT)

Enables the notify function when there are changes to low power Bluetooth device characteristic values. Note: Device characteristic values must support notify before they can be called successfully, this specifically refers to the properties attributes of characteristics.

In addition, notify must be enabled before device characteristicValueChange events can be monitored.

OBJECT parameter descriptions:

Parameter Type Required Description
deviceId string Yes Bluetooth device id, reference device object
serviceId string Yes Corresponding service UUID for Bluetooth characteristic value
characteristicId string Yes Bluetooth characteristic value UUID
state boolean Yes true: Enable notify; false: Disable notify
success Function Yes Returns local Bluetooth adapter state if successful
fail Function No Callback function for failed interface call
complete Function No Callback function for interface call results (will be executed if call succeeds or fails)

success return parameters:

Parameter Type Description
errMsg string Success: ok; error: detailed information

Sample code:

wx.notifyBLECharacteristicValueChange({
  state: true, // enable notify function
  // The deviceId here needs to be obtained from the getBluetoothDevices or onBluetoothDeviceFound interface above
  deviceId: deviceId,
  // The serviceId here needs to be obtained from the getBLEDeviceServices interface above
  serviceId: serviceId,
  // The characteristicId here needs to be obtained from the getBLEDeviceCharacteristics interface above
  characteristicId: characteristicId,
  success: function (res) {
    console.log('notifyBLECharacteristicValueChange success', res.errMsg)
  }
})

wx.onBLEConnectionStateChange(CALLBACK)

Monitors low power Bluetooth connection error events, including device losses, abnormal disconnections, etc.

CALLBACK parameter descriptions:

Parameter Type Description
deviceId string Bluetooth device id, reference device object
connected boolean Current connection state

Sample code:

wx.onBLEConnectionStateChange(function(res) {
  // This method's callback can be used to process anomalies such as accidental disconnection
  console.log(`device ${res.deviceId} state has changed, connected: ${res.connected}`)
})

wx.onBLECharacteristicValueChange(CALLBACK)

Monitors changes to low power Bluetooth device characteristic values. The notify interface must be enabled before the device's push notifications can be received.

CALLBACK parameter descriptions:

Parameter Type Description
deviceId string Bluetooth device id, reference device object
serviceId string Service UUID for characteristic value
characteristicId string Characteristic value UUID
value ArrayBuffer Latest value of characteristic value

Sample code:

wx.onBLECharacteristicValueChange(function(res) {
  console.log(`characteristic ${res.characteristicId} has changed, now is ${res.value}`)
})

Bluetooth error code (errCode) list

Error code Description Remarks
0 ok OK
10000 not init Bluetooth adapter is not initialized
10001 not available Bluetooth adapter currently not available
10002 no device Specified device not found
10003 connection fail Connection failed
10004 no service Specified service not found
10005 no characteristic Specified characteristic value not found
10006 no connection Currently disconnected
10007 property not support Characteristic value currently does not support this action
10008 system error All remaining abnormalities reported by system
10009 system not support Specific to Android systems, system versions earlier than 4.3 do not support BLE
10010 no descriptor Specified descriptor not found