SUOTA Library - 蓝牙固件升级库 #

SUOTA 0.2.5 和0.2.6开始支持鸿蒙HarmonyOS平台

概述 #

SUOTA (Software Update Over The Air) 是一个用于通过蓝牙进行固件无线升级的库。本库针对HarmonyOS平台进行了深度优化，提供了高效、稳定的固件升级解决方案。

主要特性 #

🚀 性能优化 #

• 自适应块大小传输: 根据网络状况动态调整传输块大小，提升传输效率
• GATT操作批处理: 减少蓝牙通信开销，提高数据传输速度
• 智能缓冲管理: 优化内存使用，减少GC压力

🛡️ 可靠性保障 #

• 智能重试机制: 支持连接、GATT操作、数据传输的自动重试
• 熔断器模式: 防止系统在持续失败时过度重试
• 指数退避算法: 避免网络拥塞，提高重试成功率
• 错误恢复机制: 自动检测和恢复各种异常情况

📊 监控与统计 #

• 实时性能监控: 监控连接状态、传输速度、错误率等关键指标
• 详细统计报告: 提供连接、传输、GATT操作的详细统计信息
• 资源使用监控: 监控内存、CPU使用情况

快速开始 #

1. 基本使用 #

import { SuotaManager, SuotaFile, SuotaManagerDelegate } from './SuotaLib';

// 创建SUOTA管理器
const suotaManager = new SuotaManager();

// 实现委托接口
class MyDelegate implements SuotaManagerDelegate {
  onConnectionStateChanged(status: SuotaManagerStatus): void {
    console.log(`连接状态变化: ${status}`);
  }
  
  onUpgradeProgress(progress: number): void {
    console.log(`升级进度: ${progress}%`);
  }
  
  onUpgradeCompleted(): void {
    console.log('升级完成');
  }
  
  onUpgradeFailed(error: number): void {
    console.log(`升级失败: ${error}`);
  }
}

// 设置委托
suotaManager.setDelegate(new MyDelegate());

// 加载固件文件
const suotaFile = new SuotaFile();
await suotaFile.loadFromFile('/path/to/firmware.img');
suotaManager.setSuotaFile(suotaFile);

// 连接设备并开始升级
await suotaManager.connectToDevice('device-id');
await suotaManager.startUpgrade();

2. 高级配置 #

// 配置自适应传输参数
suotaManager.setChunkSize(244); // 设置基础块大小
suotaManager.setBlockSize(512); // 设置块大小

// 获取性能统计
const stats = suotaManager.getPerformanceReport();
console.log('性能统计:', stats);

// 重置统计信息
suotaManager.resetPerformanceStats();

// 导出性能数据
const performanceData = suotaManager.exportPerformanceData();

架构设计 #

核心组件 #

1. SuotaManager: 主要管理类，负责整个升级流程的协调
2. SuotaProtocol: 协议处理类，实现SUOTA协议的具体逻辑
3. SuotaFile: 文件处理类，负责固件文件的解析和分块
4. SendChunkOperation: 数据传输操作类，实现高效的数据传输

优化机制 #

1. 自适应传输优化

// 自动调整块大小
private getAdaptiveChunkSize(): number {
  const optimalSize = SendChunkOperation.getOptimalChunkSize();
  return Math.min(this.chunkSize, optimalSize);
}

2. GATT操作批处理

// 批量处理GATT操作
private async executeBatchOperations(operations: GattOperation[]): Promise<void> {
  const batchSize = this.calculateOptimalBatchSize();
  for (let i = 0; i < operations.length; i += batchSize) {
    const batch = operations.slice(i, i + batchSize);
    await this.processBatch(batch);
  }
}

3. 智能重试机制

// 带重试的连接
private async connectWithRetry(deviceId: string): Promise<boolean> {
  const maxRetries = SuotaManager.RETRY_CONFIG.MAX_CONNECTION_RETRIES;
  
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      if (this.isCircuitBreakerOpen()) {
        throw new Error('Circuit breaker is open');
      }
      
      const success = await this.performConnection(deviceId);
      if (success) {
        this.resetConnectionRetries();
        return true;
      }
    } catch (error) {
      if (attempt < maxRetries) {
        const delay = this.calculateRetryDelay(attempt, baseDelay);
        await this.delay(delay);
      } else {
        this.openCircuitBreaker();
        throw error;
      }
    }
  }
  
  return false;
}

配置参数 #

重试配置 #

private static readonly RETRY_CONFIG = {
  MAX_CONNECTION_RETRIES: 3,        // 最大连接重试次数
  MAX_GATT_OPERATION_RETRIES: 5,    // 最大GATT操作重试次数
  MAX_TRANSFER_RETRIES: 3,          // 最大传输重试次数
  CONNECTION_RETRY_DELAY: 2000,     // 连接重试延迟(ms)
  GATT_RETRY_DELAY: 1000,          // GATT重试延迟(ms)
  TRANSFER_RETRY_DELAY: 500,        // 传输重试延迟(ms)
  EXPONENTIAL_BACKOFF_FACTOR: 1.5,  // 指数退避因子
  MAX_RETRY_DELAY: 10000,          // 最大重试延迟(ms)
  TIMEOUT_THRESHOLD: 30000,         // 超时阈值(ms)
  RECOVERY_COOLDOWN: 5000          // 恢复冷却时间(ms)
};

传输配置 #

// 块大小范围: 1-512字节
suotaManager.setBlockSize(512);

// 分片大小范围: 1-244字节
suotaManager.setChunkSize(244);

性能监控 #

统计指标 #

• 连接统计: 连接尝试次数、成功次数、失败次数、平均连接时间
• 传输统计: 总传输次数、成功次数、失败次数、总传输字节数、平均传输速度
• GATT统计: GATT操作次数、失败次数、平均操作时间
• 错误统计: 超时错误、断连错误、数据损坏错误
• 资源统计: 内存使用、CPU使用、电池影响

使用示例 #

// 获取性能报告
const report = suotaManager.getPerformanceReport();
console.log('连接成功率:', report.connectionSuccessRate);
console.log('平均传输速度:', report.averageTransferSpeed);
console.log('错误率:', report.errorRate);

// 导出详细数据
const detailedData = suotaManager.exportPerformanceData();
// 可以保存到文件或发送到服务器进行分析

错误处理 #

错误类型 #

1. 连接错误: 设备连接失败、连接超时、连接断开
2. GATT错误: 服务发现失败、特征值读写失败
3. 传输错误: 数据传输失败、校验错误、超时
4. 协议错误: 协议解析错误、状态错误

错误恢复 #

库提供了自动错误恢复机制:

1. 自动重试: 对于临时性错误，自动进行重试
2. 熔断器: 防止持续失败时的过度重试
3. 资源清理: 错误发生时自动清理资源
4. 状态重置: 恢复到可用状态

最佳实践 #

1. 连接管理 #

// 在连接前检查设备状态
if (suotaManager.isConnected()) {
  await suotaManager.disconnect();
}

// 设置合适的超时时间
suotaManager.setConnectionTimeout(30000);

2. 文件处理 #

// 验证文件完整性
if (!suotaFile.isValid()) {
  throw new Error('Invalid firmware file');
}

// 检查文件大小
if (suotaFile.getSize() > MAX_FILE_SIZE) {
  throw new Error('File too large');
}

3. 错误处理 #

try {
  await suotaManager.startUpgrade();
} catch (error) {
  // 记录错误信息
  console.error('Upgrade failed:', error);
  
  // 清理资源
  await suotaManager.cleanup();
  
  // 通知用户
  showErrorMessage(error.message);
}

4. 性能优化 #

// 根据设备性能调整参数
const deviceInfo = await getDeviceInfo();
if (deviceInfo.isLowEnd) {
  suotaManager.setChunkSize(128); // 使用较小的块大小
} else {
  suotaManager.setChunkSize(244); // 使用最大块大小
}

// 定期监控性能
setInterval(() => {
  const stats = suotaManager.getPerformanceReport();
  if (stats.errorRate > 0.1) { // 错误率超过10%
    // 调整传输参数或重新连接
  }
}, 10000);

故障排除 #

常见问题 #

1. 连接失败

   • 检查设备是否在范围内
   • 确认设备支持SUOTA协议
   • 检查蓝牙权限

2. 传输缓慢

   • 调整块大小参数
   • 检查信号强度
   • 减少其他蓝牙活动

3. 升级失败

   • 验证固件文件完整性
   • 检查设备电量
   • 确保升级过程中设备不移动

调试信息 #

启用详细日志:

// 在开发环境中启用调试日志
hilog.isLoggable(0x0000, 'SuotaManager', hilog.LogLevel.DEBUG);

版本历史 #

v2.0.0 (当前版本) #

• ✅ 实现GATT操作批处理机制
• ✅ 优化数据传输性能，支持自适应块大小
• ✅ 添加性能监控和统计功能
• ✅ 增强错误恢复和重试机制
• ✅ 完善文档和使用示例

v1.0.0 #

• 基础SUOTA协议实现
• 基本的固件升级功能

许可证 #

本项目采用 MIT 许可证。详见 LICENSE 文件。

贡献 #

欢迎提交 Issue 和 Pull Request 来改进本库。

联系方式 #

如有问题或建议，请通过以下方式联系:

• 提交 GitHub Issue
• 发送邮件至项目维护者