ESP Flutter SDK #

一个用于ESP设备蓝牙和WiFi配网的Flutter SDK。本SDK封装了Espressif的ESP-IDF配网Android库，提供了简单易用的Flutter接口。

功能特性 #

• ✅ BLE（蓝牙低功耗）设备扫描
• ✅ WiFi（SoftAP）设备扫描
• ✅ QR码扫描创建设备
• ✅ 安全连接（支持Security 0/1/2）
• ✅ WiFi网络扫描
• ✅ 设备配网（发送WiFi凭证）
• ✅ 自定义数据传输
• ✅ 事件回调机制

支持的平台 #

• ✅ Android (API 24+)
• ⚠️ iOS（待实现）

安装 #

在您的 pubspec.yaml 文件中添加依赖：

dependencies:
  esp_flutter_sdk:
    path: ../esp_flutter_sdk  # 使用本地路径，或发布到pub.dev后使用版本号

使用示例 #

1. 初始化配网管理器 #

import 'package:esp_flutter_sdk/esp_flutter_sdk.dart';

// 获取单例实例
final espManager = ESPProvisioningManager.getInstance();

2. 扫描BLE设备 #

// 注册BLE扫描回调
espManager.onBleDeviceFound((device) {
  print('发现BLE设备: ${device.name}, RSSI: ${device.rssi}');
});

espManager.onBleScanCompleted(() {
  print('BLE扫描完成');
});

espManager.onBleScanFailed((error) {
  print('BLE扫描失败: $error');
});

// 开始扫描（可选前缀过滤）
await espManager.searchBleEspDevices(prefix: 'PROV_');

// 停止扫描
await espManager.stopBleScan();

3. 创建ESP设备 #

// 方式1：手动创建设备
final device = await espManager.createESPDevice(
  transportType: TransportType.ble,
  securityType: SecurityType.security2,
);

// 方式2：从QR码创建设备
final qrData = '{"ver":"v1","name":"PROV_123456","pop":"abcd1234","transport":"ble","security":2}';
final device = await espManager.createDeviceFromQRCode(qrData);

4. 连接设备 #

// BLE连接
await device.connectBLEDevice('00:11:22:33:44:55', 'service-uuid');

// WiFi连接
await device.connectWiFiDevice('DEVICE_SSID', 'password');

// 设置POP和用户名（Security 2需要）
device.setProofOfPossession('abcd1234');
device.setUserName('username');

5. 扫描WiFi网络 #

try {
  final wifiList = await device.scanNetworks();
  for (var ap in wifiList) {
    print('WiFi: ${ap.wifiName}, RSSI: ${ap.rssi}, Security: ${ap.security}');
  }
} catch (e) {
  print('扫描网络失败: $e');
}

6. 配网设备 #

// 注册配网回调
espManager.onWifiConfigSent(() {
  print('WiFi配置已发送');
});

espManager.onWifiConfigApplied(() {
  print('WiFi配置已应用');
});

espManager.onProvisioningSuccess(() {
  print('配网成功！');
});

espManager.onProvisioningFailed((error, reason) {
  print('配网失败: $error');
  if (reason != null) {
    switch (reason) {
      case ProvisionFailureReason.authFailed:
        print('认证失败');
        break;
      case ProvisionFailureReason.networkNotFound:
        print('网络未找到');
        break;
      case ProvisionFailureReason.deviceDisconnected:
        print('设备断开连接');
        break;
      case ProvisionFailureReason.unknown:
        print('未知错误');
        break;
    }
  }
});

// 开始配网
await device.provision('YourWiFiSSID', 'YourWiFiPassword');

7. 断开连接 #

await device.disconnectDevice();

8. 清理资源 #

espManager.dispose();

完整示例 #

import 'package:flutter/material.dart';
import 'package:esp_flutter_sdk/esp_flutter_sdk.dart';

class ProvisioningPage extends StatefulWidget {
  @override
  _ProvisioningPageState createState() => _ProvisioningPageState();
}

class _ProvisioningPageState extends State<ProvisioningPage> {
  final espManager = ESPProvisioningManager.getInstance();
  List<BleDevice> bleDevices = [];
  ESPDevice? currentDevice;

  @override
  void initState() {
    super.initState();
    setupCallbacks();
  }

  void setupCallbacks() {
    espManager.onBleDeviceFound((device) {
      setState(() {
        bleDevices.add(device);
      });
    });

    espManager.onProvisioningSuccess(() {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text('配网成功！')),
      );
    });

    espManager.onProvisioningFailed((error, reason) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text('配网失败: $error')),
      );
    });
  }

  Future<void> startBleScan() async {
    bleDevices.clear();
    await espManager.searchBleEspDevices(prefix: 'PROV_');
  }

  Future<void> connectAndProvision(BleDevice bleDevice) async {
    try {
      // 创建设备
      currentDevice = await espManager.createESPDevice(
        transportType: TransportType.ble,
        securityType: SecurityType.security2,
      );

      // 连接设备
      await currentDevice!.connectBLEDevice(
        bleDevice.address,
        bleDevice.primaryServiceUuid ?? '',
      );

      // 扫描WiFi网络
      final wifiList = await currentDevice!.scanNetworks();
      
      // 选择WiFi并配网
      await currentDevice!.provision('YourWiFi', 'YourPassword');
    } catch (e) {
      print('错误: $e');
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('ESP设备配网')),
      body: ListView.builder(
        itemCount: bleDevices.length,
        itemBuilder: (context, index) {
          final device = bleDevices[index];
          return ListTile(
            title: Text(device.name),
            subtitle: Text('RSSI: ${device.rssi}'),
            onTap: () => connectAndProvision(device),
          );
        },
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: startBleScan,
        child: Icon(Icons.search),
      ),
    );
  }

  @override
  void dispose() {
    espManager.dispose();
    super.dispose();
  }
}

权限配置 #

Android #

在 android/app/src/main/AndroidManifest.xml 中添加必要的权限：

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />

API参考 #

ESPProvisioningManager #

配网管理器（单例类）

方法

• getInstance() - 获取单例实例
• createESPDevice({required TransportType, required SecurityType}) - 创建ESP设备
• getEspDevice() - 获取当前设备
• searchBleEspDevices({String? prefix}) - 搜索BLE设备
• stopBleScan() - 停止BLE扫描
• searchWiFiEspDevices({String? prefix}) - 搜索WiFi设备
• createDeviceFromQRCode(String qrCodeData) - 从QR码创建设备

回调注册

• onBleDeviceFound(Function(BleDevice)) - BLE设备发现回调
• onBleScanCompleted(Function()) - BLE扫描完成回调
• onBleScanFailed(Function(String)) - BLE扫描失败回调
• onDeviceConnected(Function()) - 设备连接成功回调
• onDeviceConnectionFailed(Function(String)) - 设备连接失败回调
• onProvisioningSuccess(Function()) - 配网成功回调
• onProvisioningFailed(Function(String, ProvisionFailureReason?)) - 配网失败回调

ESPDevice #

ESP设备类

方法

• connectToDevice() - 连接设备
• connectBLEDevice(String address, String serviceUuid) - 连接BLE设备
• connectWiFiDevice([String? ssid, String? password]) - 连接WiFi设备
• disconnectDevice() - 断开设备
• scanNetworks() - 扫描WiFi网络
• provision(String ssid, String passphrase) - 配网设备
• setProofOfPossession(String pop) - 设置POP
• setUserName(String username) - 设置用户名
• getDeviceCapabilities() - 获取设备能力

故障排除 #

常见问题 #

1. BLE扫描失败

   • 确保已授予蓝牙和位置权限
   • 检查设备蓝牙是否开启
   • Android 12+需要BLUETOOTH_SCAN和BLUETOOTH_CONNECT权限

2. WiFi连接失败

   • 确保已授予WiFi和网络权限
   • 检查设备WiFi是否开启
   • SoftAP模式下确保密码正确

3. 配网失败

   • 检查WiFi凭证是否正确
   • 确保设备在配网模式
   • 检查POP和用户名设置（Security 2需要）

开发路线图 #

• ❌ iOS平台支持
• ❌ Thread网络配网支持
• ❌ 更多示例和文档
• ❌ 单元测试和集成测试

许可证 #

Copyright 2024

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

贡献 #

欢迎提交Issue和Pull Request！

致谢 #

本SDK基于Espressif的esp-idf-provisioning-android库开发。