# OpenClawSdk

**Repository Path**: wheat1224/open-claw-sdk

## Basic Information

- **Project Name**: OpenClawSdk
- **Description**: No description available
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-12
- **Last Updated**: 2026-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BreoSDK 蓝牙开发指南

本项目是一个专为 Breo 倍轻松设备设计的蓝牙 SDK，支持 BLE (Android 12+ 兼容) 和经典蓝牙 (SPP)，采用模块化设计，支持多设备连接和自动化协议解析。

## 1. 项目架构概述

项目采用**分层设计**和**插件化协议解析**架构，确保核心通信逻辑与具体产品协议完全解耦。

### 模块分工
*   **`:core` (通信核心层)**：
    *   封装了底层蓝牙通信（基于 Nordic BLE 库）。
    *   管理连接池、自动重连、MTU 请求以及权限检查。
    *   提供 `DeviceStorage` 解决 Android 系统丢失蓝牙设备名称的兼容性问题。
*   **`:device` (业务协议层)**：
    *   存放具体产品的协议解析器 (`Parser`) 和指令封装类 (`Device`)。
    *   负责将原始 `byte[]` 转换为业务 Model（如 `ScalpHeartbeat`）。
    *   提供 `DeviceManager` 作为业务侧的唯一入口。
*   **`:app` (演示应用层)**：
    *   展示扫描、连接、指令发送及数据解析的完整流程。

---

## 2. 核心设计特性

### 2.1 自动恢复设备名
SDK 会在设备连接成功后自动持久化 Mac 地址与名称的对应关系。即便设备关机或系统缓存失效，扫描时也会自动通过 `DeviceStorage` 找回名称。

### 2.2 多连接与断开区分
*   **连接池**：支持同时连接多个不同型号的设备。
*   **状态区分**：在 `DeviceDisconnectedEvent` 中，通过 `isUserDisconnect` 字段区分是“用户手动点击断开”还是“设备由于距离过远或异常离线”。

### 2.3 消息中心化分发
所有蓝牙状态（扫描、连接、数据接收）均通过 **EventBus** 统一分发。消息包含 `source` 标识（BLE/Classic），确保 UI 知道数据来源。

---

## 3. 使用说明 (Usage Guide)

### 3.1 初始化 SDK
在 Application 或首个 Activity 中初始化 `DeviceManager`：

```java
DeviceManager deviceManager = DeviceManager.getInstance(context);
```

### 3.2 扫描设备

```java
// 获取 BLE 管理器开始扫描
deviceManager.getBleManager().startScan(10000); // 扫描10秒
```

### 3.3 连接设备与配置
连接时需传入 `DeviceConfig`，SDK 会根据配置**自动开启通知**：

```java
DeviceConfig config = new DeviceConfig(address)
    .setAutoConnect(true)
    .addService(new DeviceConfig.ServiceConfig(Scalp3sProConstants.SERVICE_UUID)
        .addCharacteristic(new DeviceConfig.CharacteristicConfig(Scalp3sProConstants.NOTIFY_UUID)
            .setEnableNotification(true))); // 设为 true，连接后自动开启通知

deviceManager.getBleManager().connectDevice(address, config);

// 注册对应的解析器
deviceManager.registerParser(address, new Scalp3sProParser());
```

### 3.4 发送指令 (以 Scalp 3s Pro 为例)

```java
Scalp3sProDevice device = new Scalp3sProDevice(address, deviceManager.getBleManager());
// 1. 发送握手
device.handshake();
// 2. 设置模式
device.setMode(Scalp3sProConstants.MODE_WORK, Scalp3sProConstants.MASSAGE_MODE_2);
```

### 3.5 接收解析后的数据
在 UI 中订阅事件，SDK 已自动完成 `byte[]` 到实体类的转换：

```java
@Subscribe(threadMode = ThreadMode.MAIN)
public void onBluetoothEvent(BluetoothEvent event) {
    if (event.getEventType() == BluetoothEvent.TYPE_DATA_RECEIVED) {
        // 获取解析后的实体类
        Object model = event.getData();
        if (model instanceof ScalpHeartbeat) {
            ScalpHeartbeat heartbeat = (ScalpHeartbeat) model;
            // 刷新 UI
        }
    }
}
```

---

## 4. 如何扩展新设备协议？

如果您有新的 MD 文档，只需三步：
1.  **定义常量**：在 `device` 模块下创建 `Constants` 类，存放 UUID 和指令码。
2.  **创建实体类**：根据 MD 文档创建对应的 POJO 类。
3.  **实现解析器**：继承 `DataParser`，实现字节解析逻辑。

---

## 5. 日志调试
使用内置的 `BleLogger` 查看完整的通信日志：
`adb logcat -s BleLogger`