支付寶小程序API 藍牙

藍牙 API 概覽

• 錯誤碼信息及解決方案，請參見下文 藍牙 API 錯誤碼對照表。
• 常見問題及解決方法，請參見下文 藍牙 API FAQ。

版本需求

基本流程

低功耗藍牙流程圖

傳統(tǒng)藍牙流程圖

藍牙 API

示例代碼

//初始化
my.openBluetoothAdapter({
  success: (res) => {
    console.log(res);
  }
});


//注冊發(fā)現(xiàn)事件
my.onBluetoothDeviceFound({
  success: (res) => {
    let device = res.devices[0];


    //連接發(fā)現(xiàn)的設備
    my.connectBLEDevice({
      deviceId: deviceId,
      success: (res) => {
        console.log(res)
      },
      fail:(res) => {
      },
      complete: (res)=>{
      }
    });


    //停止搜索
    my.stopBluetoothDevicesDiscovery({
      success: (res) => {
        console.log(res)
      },
      fail:(res) => {
      },
      complete: (res)=>{
      }
    });
  }
});

    
//注冊連接事件
my.onBLEConnectionStateChanged({
  success: (res) => {
    console.log(res);
    if (res.connected) {
        //開始讀寫notify等操作
        my.notifyBLECharacteristicValueChange({
          deviceId: deviceId,
          serviceId: serviceId,
          characteristicId: characteristicId,
          success: (res) => {
            console.log(res)
          },
          fail:(res) => {
          },
          complete: (res)=>{
          }
        });
    }
  }
});


//注冊接收read或notify的數(shù)據(jù)
my.onBLECharacteristicValueChange({
  success: (res) => {
    console.log(res);
  }
});


//開始搜索
my.startBluetoothDevicesDiscovery({
  services: ['fff0'],
  success: (res) => {
    console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});


//斷開連接
my.disconnectBLEDevice({
  deviceId: deviceId,
  success: (res) => {
    console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});


//注銷事件
my.offBluetoothDeviceFound();
my.offBLEConnectionStateChanged();
my.offBLECharacteristicValueChange();


//退出藍牙模塊
my.closeBluetoothAdapter({
  success: (res) => {
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

藍牙 API 錯誤碼對照表

藍牙 API FAQ

Q：調(diào)用 my.writeBLECharacteristicValue 的返回值是空對象嗎？

A：不是，調(diào)用此 API 返回的是您寫入成功的值。

Q：調(diào)用 my.onBLECharacteristicValueChange 為何監(jiān)聽不到？一定要先寫入才能監(jiān)聽到嗎？

A：是的，調(diào)用此 API 需要先寫入才能監(jiān)聽到。為防止多次注冊事件監(jiān)聽導致一次事件多次回調(diào)，建議每次調(diào)用 on 方法監(jiān)聽事件之前，先調(diào)用 off 方法，關閉之前的事件監(jiān)聽。

Q：調(diào)用 my.writeBLECharacteristicValue 為何報錯10014？

A：10014 錯誤是由于發(fā)送的數(shù)據(jù)為空或者格式錯誤導致，建議檢查寫入的數(shù)據(jù)或 HEX 轉(zhuǎn)化是否有錯誤。

Q：調(diào)用 my.writeBLECharacteristicValue 寫入特征值，使用 16 進制的數(shù)組可以嗎？

A：不可以，寫入特征值需要使用 16 進制的字符串，并限制在 20 字節(jié)內(nèi)。

Q：安卓和 iOS 獲取到的 deviceId 格式分別是什么樣的？

A：

• Android 獲取到的是藍牙的 mac 地址。如：11:22:33:44:55:66
• iOS 獲取到的是藍牙的 UUID。如：00000000-0000-0000-0000-000000000000

Q：調(diào)用 my.startBluetoothDevicesDiscovery 接口為何搜索不到設備？

A：請確保設備已發(fā)出廣播。若接口傳入 services，請確保設備的廣播內(nèi)容中包含 service 的 UUID。

Q：調(diào)用藍牙 API 時如果不開啟 GPS 定位，部分機型會報錯：定位服務未開啟。連接不了藍牙？

A：小程序藍牙功能需要依賴 GPS 定位，因為大概 5 分之一的手機藍牙需要依賴 GPS。 建議接入藍牙時先引導用戶打開 GPS 定位服務。

Q：如何解決連接設備失敗?

A：請確保傳入的 deviceId 正確，并且設備發(fā)出的信號足夠強。在信號弱的情況下，可能會出現(xiàn)連接設備失敗。

Q：如何解決寫 / 讀數(shù)據(jù)失敗？

A：

• 請確保傳入的 deviceId、serviceId、characteristicId 格式正確。
• deviceId 已連接上（可調(diào)用 my.onBLEConnectionStateChanged 監(jiān)聽連接狀態(tài)的變化；調(diào)用 my.getConnectedBluetoothDevices 獲取處于已連接狀態(tài)的設備。）
• 在連接狀態(tài)下寫入方法。
• 檢查 characteristicId 屬于此 service。
• 此特征值支持寫 / 讀。

Q：如何收到數(shù)據(jù)通知？

A：

• 請確保已調(diào)用 my.notifyBLECharacteristicValueChange 方法，并且傳入的參數(shù)正確。
• 傳入的 characteristicId 特征值支持 notify 或 indicate 操作。
• 確保硬件已發(fā)出通知。
• 注意基本流程順序，在連接之后就調(diào)用 my.notifyBLECharacteristicValueChange 方法。

Q：為何事件回調(diào)會多次被調(diào)用？

A：由于多次匿名函數(shù)注冊監(jiān)聽了同一事件。所以建議在每次調(diào)用 on 方法監(jiān)聽事件之前，先調(diào)用 off 方法關閉之前的事件監(jiān)聽。