# SA255A 玩具控制协议

## 硬件信息

- 品牌：Svakom（司沃康偏欣）
- 型号：SA255A
- BLE 广播名：SA255A
- MAC：B7B76384-3586-0B4D-11E8-F633CEDBCEC8（可能随机变化）

## GATT 结构

| 服务 | UUID | 用途 |
|------|------|------|
| 控制服务 | `0000ffe0-0000-1000-8000-00805f9b34fb` | 震动控制 |
| 写特征 | `0000ffe1-0000-1000-8000-00805f9b34fb` | Write No Response |
| 通知特征 | `0000ffe2-0000-1000-8000-00805f9b34fb` | Notify（状态回传） |
| OTA服务 | `0000ae00-0000-1000-8000-00805f9b34fb` | 固件升级（禁止写入） |

## 震动指令格式

```
55 <func> 00 00 <mode> <intensity> 00
```

| 字节 | 含义 | 取值范围 |
|------|------|---------|
| [0] | 帧头 | `0x55`（固定） |
| [1] | 功能码 | `0x08` = 震动 |
| [2-3] | 保留 | `0x00 0x00` |
| [4] | 模式 | `0x01`-`0x03`（变化不大） |
| [5] | 强度 | `0x01`-`0x05`（实测差异不明显） |
| [6] | 保留 | `0x00` |

**示例**：
- 震动模式1 强度3：`55 08 00 00 01 03 00`
- 震动模式1 最低：`55 08 00 00 01 01 00`

## 停指令

**未知**。实测 `55 FE 08 00 00 00 00`、`55 08 00 00 01 00 00`、全零等均无效。当前用 **BLE 断开连接** 作为停止方式（玩具自动停）。

## Notify 回传格式

```
55 87 00 00 <mode> <intensity>
```

- `0x87` = 状态回传标志
- 仅回传当前运行模式/强度，**无压力/力反馈数据**
- 需要持久事件循环才能收到（已修复）

## 力反馈

**SA255A 不支持**。Notify 通道只有指令回显，无压力传感器读数。产品详情页的"力反馈"可能是营销措辞或仅官方 App 内部处理。

## 控制链路

```
Claude Code → toy.py → BLE bridge (:8796) → bleak → BLE → SA255A
                ↑ 权限白名单已配
```

- `python3 /tmp/CcCompanion/apns-server/toy.py scan` — 扫描
- `python3 /tmp/CcCompanion/apns-server/toy.py connect [addr]` — 连接
- `python3 /tmp/CcCompanion/apns-server/toy.py on [1-5]` — 震动
- `python3 /tmp/CcCompanion/apns-server/toy.py off` — 断开停
- `python3 /tmp/CcCompanion/apns-server/toy.py feedback` — 读 Notify

## BLE Bridge

- 端口：8796
- 持久事件循环（保证 Notify 回调）
- SessionStart hook 自动拉起
- 写入模式：Write Without Response

## 权限

`Bash(python3 */toy.py *)` 加入 `~/.claude/settings.json` allowlist，无需用户批准。