donehome-sdk

donehome-sdk

DoneHome BLE SDK — 私有化 BLE 模组控制 SDK

特性

• 📱 React / Vue — 基于 Web Bluetooth API
• 🎮 微信小程序 (mina) — 原生 wx BLE API
• 🖥️ Express / Node.js — 基于 @abandonware/noble
• 📦 TypeScript — 完整类型定义
• 🔧 模块化设计 — Scanner / Connector / Provisioner / Auth / Controller

安装

npm install donehome-sdk

Node.js / Express 额外依赖

npm install @abandonware/noble

快速开始

导入方式

// 命名导入（推荐）
import { Scanner, Connector, Provisioner, Auth, Controller, DoneHomeSDK } from 'donehome-sdk';

// 或使用默认导入
import DoneHomeSDK from 'donehome-sdk';

基础用法

import { DoneHomeSDK, Scanner, Connector, Controller } from 'donehome-sdk';

// 1. 初始化 SDK
const sdk = new DoneHomeSDK({ debug: true });
await sdk.init();

// 2. 使用 Scanner 扫描设备
const scanner = new Scanner(sdk);
await scanner.start({ service_uuid: '0000ff01-0000-1000-8000-00805f9b34fb', rssi_min: -80 });

// 获取发现的设备列表
const devices = scanner.getDevices();
console.log('发现设备:', devices);
await scanner.stop();

// 3. 使用 Connector 连接设备
const connector = new Connector(sdk);
await connector.connect(devices[0].deviceId, {
  timeout_ms: 10000,
  auto_reconnect: true,
  reconnect_count: 3,
});

// 4. 使用 Controller 控制设备
const controller = new Controller(sdk);
await controller.send_cmd(devices[0].deviceId, {
  code: 0x01,
  payload: new Uint8Array([0x01, 0x02]),
  require_ack: true,
  timeout_ms: 5000,
});

微信小程序

import { DoneHomeSDK, Scanner, Connector, Controller } from 'donehome-sdk/wechat';

const sdk = new DoneHomeSDK({ debug: true });
await sdk.init();

const scanner = new Scanner(sdk);
await scanner.start();

模块说明

DoneHomeSDK（核心）

初始化和管理 BLE 适配器，提供底层 BLE 操作。

const sdk = new DoneHomeSDK({ debug: true });
await sdk.init(); // 自动检测平台并加载对应适配器

Scanner — 设备扫描

const scanner = new Scanner(sdk);

// 开始扫描（支持过滤）
await scanner.start({
  service_uuid: '0000ff01-...', // 按服务 UUID 过滤
  rssi_min: -80,                // RSSI 最低值
});

// 获取已发现设备
const devices = scanner.getDevices();
// [{ deviceId: '...', name: '...', rssi: -65 }, ...]

// 停止扫描
await scanner.stop();

方法：

Connector — 设备连接

const connector = new Connector(sdk);

// 连接设备
await connector.connect('device_id', {
  timeout_ms: 10000,
  auto_reconnect: true,
  reconnect_count: 3,
});

// 获取连接状态
const state = connector.get_connect_state('device_id');
// 'disconnected' | 'connecting' | 'connected' | 'disconnecting'

// 断开连接
await connector.disconnect('device_id');

方法：

Provisioner — 设备配网

const provisioner = new Provisioner(sdk);

// 发起配网
await provisioner.provision('device_id', {
  ssid: 'MyWiFi',
  password: 'password123',
});

// 取消配网
await provisioner.cancel('device_id');

// 获取配网状态
const state = provisioner.getState('device_id');
// 'idle' | 'provisioning' | 'success' | 'failed' | 'cancelled'

方法：

Auth — 配网认证

const auth = new Auth(sdk);

// 发起认证（challenge-response）
const result = await auth.auth('device_id', {
  key: 'your-secret-key',
  timeout_ms: 10000,
});
console.log('session_key:', result.session_key);

// 刷新 session key
await auth.refresh_session('device_id');

// 获取缓存的 session
const session = auth.getSession('device_id');

方法：

Controller — 设备控制

const controller = new Controller(sdk);

// 发送指令（需要 ACK）
const ack = await controller.send_cmd('device_id', {
  code: 0x01,
  payload: new Uint8Array([0x01, 0x02]),
  encrypt: false,
  require_ack: true,
  timeout_ms: 5000,
});

// 读取特征值
const data = await controller.read_char('device_id', 'characteristic-uuid');

// 写入特征值
await controller.write_char('device_id', 'characteristic-uuid', new Uint8Array([0x01]));

// 订阅特征值通知
await controller.sub_char('device_id', 'characteristic-uuid', (data) => {
  console.log('收到数据:', new Uint8Array(data));
});

// 取消订阅
await controller.unsub_char('device_id', 'characteristic-uuid');

方法：

静态工具方法

import { version, info } from 'donehome-sdk';

console.log(version());
// { version: '1.0.1010', buildTime: '2026-10-10T...' }

console.log(info());
// { author: 'don' }

输出格式

License

MIT © don