跳到主要内容

设备配网功能

芯相随微信小程序 SDK 基于微信小程序蓝牙通信能力实现，请注意基础库支持。参考：微信小程序蓝牙低功耗

蓝牙配网的相关 API，分为高阶 API 和低阶 API :

  • 高阶 API 封装了更多默认行为，开发者需要关注的细节更少。由于占用了蓝牙扫描功能，不能与小程序已有的蓝牙扫描逻辑同时使用。
  • 低阶 API 仅包含了核心的配网步骤，因此开发者需要自行管理蓝牙的扫描，不会对小程序原有的蓝牙逻辑产生影响。对于原本有蓝牙扫描功能（例如同时扫描其他厂商设备）的小程序，建议选择性的用 低阶 API 实现相应功能。

配网流程​

  • 初始化 SDK
  • 开启蓝牙功能，用 scanConfigurableDevice 扫描蓝牙设备
  • 将找出的 芯相随设备 显示到界面上，供用户选择某一台设备。
  • 用户填写 Wi-Fi 名称和密码，或者用其他方式获取。
  • 由 quickConfigureDevice 函数将其发送到指定的设备。
  • 用 stopScanDevice 停止蓝牙设备扫描，关闭蓝牙功能
请注意

开发者应编写逻辑事先检查小程序蓝牙权限，界面提醒用户打开蓝牙开关，连接网络。 安卓设备需开启【位置信息】开关才能扫描到设备。配网过程中，小程序应始终能够连接网络。

各端交互时序图​

低阶 API​

xxs.configurableDeviceFilter()​

筛选芯相随设备

代码示例：example.js
wx.onBluetoothDeviceFound(({ devices: temp }) => {
  xxs.configurableDeviceFilter({
    devices: temp,
    callback({ devices, error }) {
      console.log(devices);
      console.error(error);
    }
  });
});
类型定义（.d.ts）
interface Device {
  /** 芯相随设备序列号 */
  serial: string;
  /** 芯相随设备的蓝牙 deviceId */
  deviceId: string;
  /** 芯相随设备名称 */
  name: string;
  /** 芯相随设备预览图 */
  thumb?: string;
}

/** 发现设备的回调函数 */
function Callback(options: {
  /** 扫描出的可配网设备列表 */
  devices?: Device[];
  /** 扫描过程中出现的错误 */
  error?: SDKError;
}): void;

/** 发现芯相随BLE设备执行后调 */
declare function configurableDeviceFilter(options: {
  /** 传入 wx.onBluetoothDeviceFound() 返回的 devices */
  devices?: object[];
  /** 发现设备的回调函数 */
  callback?: Callback;
}): void;

xxs.quickConfigureDevice()​

连接设备，向设备发送配网信息，断开连接

类型定义（.d.ts）
interface Options {
  /** 目标设备蓝牙 deviceId */
  deviceId: string;
  /** Wi-Fi 名称（SSID） */
  ssid: string;
  /** Wi-Fi 密码 */
  password: string;
}

/** 连接设备，向设备发送配网信息，断开连接 */
async function quickConfigureDevice(options: Options): void;
错误码说明
2网络超时
3厂商认证错误，检查 AppID/Secret 有效性

高阶 API​

xxs.scanConfigurableDevice()​

扫描芯相随设备

代码示例：example.js
xxs.scanConfigurableDevice(({ devices, error }) => {
  if (error) {
    console.error(error);
  }

  console.log(devices);
});
类型定义（.d.ts）
interface Device {
  /** 芯相随设备序列号 */
  serial: string;
  /** 芯相随设备蓝牙 deviceId */
  deviceId: string;
  /** 芯相随设备名称 */
  name: string;
  /** 芯相随设备预览图 */
  thumb?: string;
}

interface CallbackOptions {
  devices?: Device[];
  error?: SDKError;
}

/** 发现设备的回调函数 */
function Callback(options: CallbackOptions): void;

/** 扫描芯相随设备 */
declare function scanConfigurableDevice(callback: Callback): void;
错误码说明
2网络超时
3厂商认证错误，检查 AppID/Secret 有效性
20微信小程序抛出接口错误，请查看原始错误信息

xxs.stopScanDevice()​

停止扫描芯相随设备

/** 回调函数 */
function Callback({ error }: { error?: SDKError }): void;

/** 停止扫描芯相随设备 */
declare function stopScanDevice(callback?: Callback): void;
错误码说明
20微信小程序抛出接口错误，请查看原始错误信息

通用错误码​

错误码说明
0未知错误
1参数校验错误，检查函数各输入参数类型

常见问题​

为什么需要自行调用微信小程序官方提供的蓝牙接口？​

SDK 不会擅自调用 wx.closeBluetoothAdapter() 接口，因为第三方小程序的其他逻辑可能也在使用蓝牙功能。与之相对的 wx.openBluetoothAdapter() 也需要自行调用。

基于同样的原因，低阶 API 不包含的 wx.startBluetoothDevicesDiscovery() / wx.stopBluetoothDevicesDiscovery() 也需要自行调用。这一模式的优点是，开发者能完全掌控蓝牙的扫描时机，可以支持同时扫描其他厂商的设备。

微信小程序的设计中，每次执行 wx.onBluetoothDeviceFound() 会替换先前绑定的回调，执行 wx.offBluetoothDeviceFound() 会解除所有的回调，因此 低阶 API 也不会包含这些动作。

最后于 更新