FwEnviroData SDK

方物(FANGWU)环境检测设备蓝牙通信SDK - 支持微信小程序、uni-app、React Native（react-native-ble-plx）

特性

• 跨平台支持：微信小程序、uni-app（支持多端）、React Native（react-native-ble-plx）
• 完整的设备通信协议封装
• TypeScript 类型支持，开发体验友好
• 内置设备扫描、连接、检测全流程
• 事件驱动架构，便于状态监听
• 完善的错误处理和超时机制
• 检测与设备信息查询解耦（startDetection 仅扫描与读数）
• 支持设备主动检测：startDeviceInitiatedDetection、默认触发串常量 DEFAULT_DEVICE_DETECTION_TRIGGER_TEXT

安装

npm install @insentek/fw-envirodata-sdk
# 或
yarn add @insentek/fw-envirodata-sdk

快速开始

React Native

需安装可选对等依赖 react-native-ble-plx（>=3.0），并由应用持有 BleManager 生命周期。

import { BleManager } from 'react-native-ble-plx';
import { FwEnviroDataSDK, ReactNativeAdapter } from '@insentek/fw-envirodata-sdk';

const bleManager = new BleManager();
const sdk = new FwEnviroDataSDK({
  platform: 'react-native',
  adapter: new ReactNativeAdapter(bleManager),
  debug: __DEV__,
});

await sdk.init();
await sdk.startScan({ filterFANGWU: true });
// ... connect / startDetection 等与小程序相同

await sdk.destroy();
bleManager.destroy();

完整界面与业务流可参考方物 React Native 演示应用

文档

• API 文档 - 详细的 API 参考
• 使用手册 - 完整的使用指南（含各平台权限与排错）
• 协议文档 - 设备通信协议说明
• 示例消费者指南 - 分层集成思路（小程序示例）

项目结构

fw-envirodata-sdk/
├── src/                          # 源代码
│   ├── FwEnviroDataSDK.ts        # SDK主类
│   ├── types/                    # 类型定义
│   ├── utils/                    # 工具函数
│   ├── core/                     # 核心模块
│   ├── commands/                 # 指令构建与解析
│   ├── devices/                  # 设备管理
│   ├── detection/                # 检测引擎
│   └── platform/                 # 平台适配器
├── docs/                         # 文档
├── examples/                     # 示例与集成说明
│   ├── miniprogram/              # 微信小程序示例
│   └── CONSUMER_GUIDE.md         # SDK/Service/UI 分层说明
├── dist/                         # 编译输出
└── tests/                        # 测试代码

核心功能

设备扫描

await sdk.startScan({
  filterFANGWU: true,  // 只显示FANGWU设备
  timeout: 10000,      // 10秒超时
  onDeviceFound: (device) => {
    console.log(device.name, device.deviceId);
  }
});

设备连接

// 连接
await sdk.connect(deviceId, deviceName);

// 监听连接状态
sdk.on('connected', (deviceId) => {
  console.log('已连接:', deviceId);
});

sdk.on('disconnected', (deviceId) => {
  console.log('已断开:', deviceId);
});

获取设备信息

// 获取完整设备信息
const info = await sdk.getDeviceInfo();

// 单独获取
const sn = await sdk.getSN();
const battery = await sdk.getBattery();  // { voltage, level, status }
const temperature = await sdk.getTemperature();

执行检测

// 手机发起扫描
const result = await sdk.startDetection({ maxCount: 3 });

// 设备已通过 notify 表示开始扫描时（见文档「设备主动检测」）
// await sdk.startDeviceInitiatedDetection({ maxCount: 1, deviceTriggerTimeoutMs: 0 });

// 取消检测
sdk.cancelDetection();

事件监听

// 检测事件
sdk.on('detectionstart', () => {});
sdk.on('detectioncomplete', (result) => {});
sdk.on('detectionerror', (error) => {});
sdk.on('detectioncancelled', () => {});

sdk.on('notification', (_data: ArrayBuffer) => {
  /* 原始 notify；与命令响应同源，按需解析 */
});

// 蓝牙事件
sdk.on('connected', (deviceId) => {});
sdk.on('disconnected', (deviceId) => {});
sdk.on('connectionstatechange', (state) => {});

错误处理

SDK 提供了详细的错误码，便于问题定位：

import { SDKError, ErrorCode } from '@insentek/fw-envirodata-sdk';

try {
  await sdk.connect(deviceId);
} catch (error) {
  if (error instanceof SDKError) {
    switch (error.code) {
      case ErrorCode.BLE_CONNECT_FAILED:
        // 连接失败
        break;
      case ErrorCode.BLE_READ_TIMEOUT:
        // 读取超时
        break;
      case ErrorCode.DEVICE_NOT_CONNECTED:
        // 设备未连接
        break;
    }
  }
}

兼容性

| 平台 | 版本要求 | |------|----------| | 微信小程序 | 基础库 2.3.0+ | | uni-app | Vue2/Vue3 均支持 | | React Native | react-native-ble-plx >= 3.0；系统蓝牙权限按官方文档配置 | | iOS | iOS 11.1+（RN 以 ble-plx 要求为准） | | Android | Android 5.0+（RN 以 ble-plx 要求为准） |

开发

# 安装依赖
npm install

# 编译 TypeScript
npm run build

# 运行测试
npm test

# 代码检查
npm run lint

许可证

Apache License 2.0 — 全文见仓库根目录 LICENSE，版权与归属说明见 NOTICE。

技术支持

• 问题反馈: GitHub Issues
• 邮箱: [email protected]