# LaUniBlePlugin

**Repository Path**: liulog/LaUniBlePlugin

## Basic Information

- **Project Name**: LaUniBlePlugin
- **Description**: 原生蓝牙转 uniapp 插件
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-31
- **Last Updated**: 2025-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 呼吸家蓝牙插件 (LaUniBlePlugin)

一个专为呼吸家医疗设备设计的Android蓝牙通信插件，支持设备扫描、连接管理、数据采集和实时监控功能。后续可转换为UniApp插件，支持跨平台应用开发。

## 功能特性

- 🔍 **设备扫描**: 自动扫描附近的呼吸家蓝牙设备
- 🔗 **连接管理**: 稳定的设备连接和自动重连机制
- 📊 **数据解析**: 实时解析设备数据包，支持多种医疗指标
- 📱 **事件回调**: 完整的事件监听机制，支持异步通知
- 🛡️ **错误处理**: 完善的错误分类和处理机制
- 📝 **日志记录**: 详细的日志记录，支持文件输出
- 🔄 **UniApp兼容**: 设计时考虑了UniApp转换需求

## 系统要求

- Android 5.0+ (API Level 21+)
- 支持蓝牙低功耗 (BLE)
- 必要的蓝牙和位置权限

## 快速开始

### 1. 添加依赖

在 `app/build.gradle.kts` 中添加以下依赖：

```kotlin
dependencies {
    // 蓝牙相关依赖
    implementation("androidx.bluetooth:bluetooth:1.0.0-alpha02")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
    
    // JSON解析
    implementation("com.google.code.gson:gson:2.10.1")
    
    // 权限处理
    implementation("androidx.activity:activity-ktx:1.8.2")
    implementation("androidx.fragment:fragment-ktx:1.6.2")
}
```

### 2. 配置权限

在 `AndroidManifest.xml` 中添加必要权限：

```xml
<!-- 蓝牙权限 -->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<!-- Android 12+ 蓝牙权限 -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" tools:targetApi="s" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />

<!-- 声明蓝牙功能 -->
<uses-feature
    android:name="android.hardware.bluetooth_le"
    android:required="true" />
```

### 3. 基本使用

```kotlin
class MainActivity : ComponentActivity() {
    private lateinit var plugin: LaUniBlePlugin
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // 初始化插件
        plugin = LaUniBlePlugin.getInstance(this)
        
        // 初始化插件
        val initResult = plugin.initialize()
        
        // 设置事件监听器
        setupEventListeners()
        
        // 开始扫描设备
        plugin.startScan()
    }
    
    private fun setupEventListeners() {
        // 设备发现事件
        plugin.setEventCallback("onDeviceFound") { jsonData ->
            // 处理发现的设备
            Log.d("Plugin", "发现设备: $jsonData")
        }
        
        // 设备连接事件
        plugin.setEventCallback("onDeviceConnected") { jsonData ->
            // 处理设备连接
            Log.d("Plugin", "设备已连接: $jsonData")
        }
        
        // 数据接收事件
        plugin.setEventCallback("onDataReceived") { jsonData ->
            // 处理接收到的数据
            Log.d("Plugin", "接收数据: $jsonData")
        }
        
        // 错误事件
        plugin.setEventCallback("onError") { jsonData ->
            // 处理错误
            Log.e("Plugin", "发生错误: $jsonData")
        }
    }
    
    override fun onDestroy() {
        super.onDestroy()
        plugin.cleanup()
    }
}
```

## API 接口

### 核心方法

#### 初始化插件
```kotlin
fun initialize(config: String = "{}"): String
```
- **参数**: `config` - 初始化配置（JSON字符串）
- **返回**: 初始化结果（JSON格式）

#### 检查蓝牙状态
```kotlin
fun checkBluetoothStatus(): String
```
- **返回**: 蓝牙状态信息（JSON格式）

#### 开始扫描设备
```kotlin
fun startScan(options: String = "{}"): String
```
- **参数**: `options` - 扫描选项（JSON字符串）
  - `timeout`: 扫描超时时间（毫秒）
  - `deviceName`: 设备名称过滤器
- **返回**: 扫描启动结果（JSON格式）

#### 停止扫描设备
```kotlin
fun stopScan(): String
```
- **返回**: 停止扫描结果（JSON格式）

#### 连接设备
```kotlin
fun connectDevice(deviceInfo: String): String
```
- **参数**: `deviceInfo` - 设备信息（JSON字符串）
  - `deviceId`: 设备ID
  - `macAddress`: MAC地址
  - `deviceName`: 设备名称（可选）
  - `autoReconnect`: 是否自动重连（默认true）
- **返回**: 连接结果（JSON格式）

#### 断开设备连接
```kotlin
fun disconnectDevice(deviceId: String): String
```
- **参数**: `deviceId` - 设备ID
- **返回**: 断开连接结果（JSON格式）

#### 发送数据到设备
```kotlin
fun sendData(deviceId: String, data: String): String
```
- **参数**: 
  - `deviceId`: 目标设备ID
  - `data`: 要发送的数据（十六进制字符串）
- **返回**: 发送结果（JSON格式）

#### 获取已连接设备列表
```kotlin
fun getConnectedDevices(): String
```
- **返回**: 设备列表（JSON格式）

### 事件回调

#### 设置事件回调
```kotlin
fun setEventCallback(eventType: String, callback: (String) -> Unit)
```

#### 支持的事件类型

- `onDeviceFound`: 发现设备
- `onScanCompleted`: 扫描完成
- `onDeviceConnected`: 设备连接成功
- `onDeviceDisconnected`: 设备断开连接
- `onDataReceived`: 接收到数据
- `onError`: 发生错误

## 数据格式

### 设备信息格式
```json
{
  "deviceId": "AA:BB:CC:DD:EE:FF",
  "deviceName": "呼吸家设备",
  "macAddress": "AA:BB:CC:DD:EE:FF",
  "signalStrength": -45,
  "signalDescription": "强"
}
```

### 数据记录格式
```json
{
  "recordId": "record_12345",
  "deviceId": "AA:BB:CC:DD:EE:FF",
  "dataType": "呼吸频率",
  "timestamp": 1640995200000,
  "dataPoints": [
    {
      "metricName": "respiratory_rate",
      "value": 18.5,
      "unit": "次/分钟",
      "formattedValue": "18.50 次/分钟"
    }
  ],
  "rawDataHex": "AA 01 12 34 55"
}
```

### 错误信息格式
```json
{
  "success": false,
  "error": {
    "code": 1002,
    "type": "BLUETOOTH_NOT_ENABLED",
    "message": "请先开启蓝牙功能",
    "details": "蓝牙未启用",
    "timestamp": 1640995200000
  }
}
```

## 支持的医疗数据类型

- **呼吸频率** (RESPIRATORY_RATE): 次/分钟
- **潮气量** (TIDAL_VOLUME): mL
- **分钟通气量** (MINUTE_VOLUME): L/min
- **血氧饱和度** (OXYGEN_SATURATION): %
- **心率** (HEART_RATE): 次/分钟
- **体温** (TEMPERATURE): °C
- **气道压力** (PRESSURE): cmH2O
- **流速** (FLOW_RATE): L/min

## 错误代码

| 错误代码 | 错误类型 | 描述 |
|---------|---------|------|
| 1001 | BLUETOOTH_NOT_SUPPORTED | 设备不支持蓝牙 |
| 1002 | BLUETOOTH_NOT_ENABLED | 蓝牙未启用 |
| 2001 | PERMISSION_DENIED | 权限被拒绝 |
| 3001 | SCAN_FAILED_ALREADY_STARTED | 扫描已在进行中 |
| 4001 | CONNECTION_FAILED_ESTABLISHMENT | 连接建立失败 |
| 4002 | CONNECTION_TIMEOUT | 连接超时 |
| 6001 | DATA_PARSING_FAILED | 数据解析失败 |
| 9001 | PLUGIN_NOT_INITIALIZED | 插件未初始化 |

## 日志配置

```kotlin
// 初始化日志系统
Logger.initialize(
    logDir = getExternalFilesDir("logs"),
    enableFile = true,
    minLevel = LogLevel.DEBUG
)

// 记录日志
Logger.d("TAG", "调试信息")
Logger.i("TAG", "普通信息")
Logger.w("TAG", "警告信息")
Logger.e("TAG", "错误信息", exception)
```

## 最佳实践

### 1. 权限处理
```kotlin
private fun requestBluetoothPermissions() {
    val permissions = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        BluetoothConstants.BLUETOOTH_PERMISSIONS_API31
    } else {
        BluetoothConstants.BLUETOOTH_PERMISSIONS
    }
    
    val missingPermissions = permissions.filter {
        ContextCompat.checkSelfPermission(this, it) != PackageManager.PERMISSION_GRANTED
    }
    
    if (missingPermissions.isNotEmpty()) {
        requestPermissionLauncher.launch(missingPermissions.toTypedArray())
    }
}
```

### 2. 连接管理
```kotlin
// 启用自动重连
val deviceInfo = mapOf(
    "deviceId" to device.deviceId,
    "macAddress" to device.macAddress,
    "autoReconnect" to true
)
plugin.connectDevice(Gson().toJson(deviceInfo))
```

### 3. 错误处理
```kotlin
plugin.setEventCallback("onError") { jsonData ->
    try {
        val response = Gson().fromJson(jsonData, Map::class.java)
        val error = response["error"] as? Map<String, Any>
        val errorCode = error?.get("code") as? Double
        
        when (errorCode?.toInt()) {
            1002 -> showBluetoothEnableDialog()
            2001 -> requestPermissions()
            4002 -> retryConnection()
            else -> showGenericError(error?.get("message") as? String)
        }
    } catch (e: Exception) {
        Log.e("Error", "处理错误事件失败", e)
    }
}
```

## UniApp 转换指南

### 1. 插件结构
插件已按照UniApp原生插件的结构设计，主要包括：
- 统一的JSON API接口
- 事件回调机制
- 错误处理规范

### 2. 接口映射
```javascript
// UniApp中的调用方式
const plugin = uni.requireNativePlugin('LaUniBlePlugin');

// 初始化
plugin.initialize({}, (result) => {
    console.log('初始化结果:', result);
});

// 设置事件监听
plugin.setEventCallback('onDeviceFound', (data) => {
    console.log('发现设备:', data);
});

// 开始扫描
plugin.startScan({ timeout: 10000 }, (result) => {
    console.log('扫描结果:', result);
});
```

### 3. 事件处理
```javascript
// 在UniApp中处理事件
export default {
    data() {
        return {
            devices: [],
            connectedDevices: []
        }
    },
    
    onLoad() {
        this.initPlugin();
    },
    
    methods: {
        initPlugin() {
            const plugin = uni.requireNativePlugin('LaUniBlePlugin');
            
            plugin.setEventCallback('onDeviceFound', (data) => {
                const device = JSON.parse(data).data;
                this.devices.push(device);
            });
            
            plugin.setEventCallback('onDataReceived', (data) => {
                const record = JSON.parse(data).data;
                this.handleDataReceived(record);
            });
        }
    }
}
```

## 故障排除

### 常见问题

1. **扫描不到设备**
   - 检查蓝牙是否开启
   - 确认位置权限已授予
   - 验证设备是否在广播模式

2. **连接失败**
   - 检查设备是否已被其他应用连接
   - 确认蓝牙连接权限
   - 尝试重启蓝牙适配器

3. **数据解析失败**
   - 检查设备协议是否匹配
   - 验证数据包格式
   - 查看详细错误日志

### 调试技巧

1. **启用详细日志**
```kotlin
Logger.setMinLogLevel(LogLevel.VERBOSE)
```

2. **查看错误历史**
```kotlin
val errorHistory = ErrorHandler.getErrorHistory()
Log.d("Debug", "错误历史: $errorHistory")
```

3. **检查插件状态**
```kotlin
val status = plugin.checkBluetoothStatus()
Log.d("Debug", "插件状态: $status")
```

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request来改进这个插件。

## 更新日志

### v1.0.0
- 初始版本发布
- 支持基本的蓝牙设备扫描和连接
- 实现数据解析和事件回调
- 添加完整的错误处理机制
- 提供详细的日志记录功能

## 联系方式

如有问题或建议，请通过以下方式联系：
- 项目地址: https://gitee.com/liulog/LaUniBlePlugin.git
- 邮箱: support@huxijia.cn
- 官网: www.huxijia.cn