1429 lines
51 KiB
Markdown
1429 lines
51 KiB
Markdown
# Eskin Finger SDK — 架构设计文档
|
||
|
||
## 1. 概述
|
||
|
||
**Eskin Finger SDK** 是一款高性能压敏薄膜传感器数据采集 SDK，用于采集手套式压力传感器阵列的分布力数据（五指 + 掌心共 28 个传感器模组）。采用三层架构设计：
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ C++ Wrapper (RAII + Callback) │
|
||
│ cpp/include/eskin_finger_sdk.hpp │
|
||
│ cpp/src/eskin_finger_sdk.cpp │
|
||
├─────────────────────────────────────────────────┤
|
||
│ C ABI Layer (FFI) │
|
||
│ include/eskin_finger_sdk.h │
|
||
│ src/ffi/c_api.rs │
|
||
├─────────────────────────────────────────────────┤
|
||
│ Rust Core (Channel + Thread) │
|
||
│ src/lib.rs, device.rs, stream.rs │
|
||
│ src/channel.rs, types.rs, error.rs │
|
||
│ src/protocol.rs, src/transport.rs │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
- **Rust Core**：UART 通信、协议解析、数据采集线程、Channel 通信、错误管理
|
||
- **C ABI Layer**：通过 `#[repr(C)]` 和 `extern "C"` 提供稳定的 FFI 接口
|
||
- **C++ Wrapper**：RAII 封装、异常处理、回调机制
|
||
|
||
---
|
||
|
||
## 2. 通信协议概述
|
||
|
||
### 2.1 UART 物理层
|
||
|
||
| 参数 | 值 |
|
||
|------|-----|
|
||
| 波特率 | 115200 |
|
||
| 数据位 | 8 bit |
|
||
| 停止位 | 1 位 |
|
||
| 校验位 | NONE |
|
||
| 通信模式 | 请求-应答（主从模式） |
|
||
|
||
### 2.2 帧结构
|
||
|
||
#### 读请求帧
|
||
|
||
```
|
||
┌────────┬──────────┬────────────┬────────┬────────┬──────────┬──────────────┬───────────┬────────┐
|
||
│ 起始符 │ 数据长度 │ 设备地址 │ 预留 │功能码 │ 起始地址 │ 读取数据长度 │ CRC-8 │ │
|
||
│ 0x55AA │ 2B(LE) │ 1B │ 0x00 │ 0xFB │ 4B(LE) │ 2B(LE) │ 1B │ │
|
||
├────────┼──────────┼────────────┼────────┼────────┼──────────┼──────────────┼──────────┼────────┤
|
||
│data[0-1]│data[2-3]│ data[4] │data[5] │data[6] │data[7-10]│ data[11-12] │ data[13] │ │
|
||
└────────┴──────────┴────────────┴────────┴────────┴──────────┴──────────────┴──────────┘
|
||
```
|
||
|
||
#### 读应答帧
|
||
|
||
```
|
||
┌────────┬──────────┬────────────┬────────┬────────────┬──────────┬───────────┬──────────┬────────┬────────┐
|
||
│ 起始符 │ 数据长度 │ 设备地址 │ 预留 │ 功能码 │ 起始地址 │ 读取数据 │ CRC-8 │ 状态 │ │
|
||
│ 0xAA55 │ 2B(LE) │ 1B │ 0x00 │ 0x80+func │ 4B(LE) │ 2B(LE) │ 1B │ 1B │ │
|
||
├────────┼──────────┼────────────┼────────┼────────────┼──────────┼───────────┼──────────┼────────┤
|
||
│data[0-1]│data[2-3]│ data[4] │data[5] │ data[6] │data[7-10]│data[11-12]│data[N+13]│data[13]│ │
|
||
└────────┴──────────┴────────────┴────────┴────────────┴──────────┴───────────┴──────────┴────────┘
|
||
```
|
||
|
||
#### 写请求帧
|
||
|
||
```
|
||
┌────────┬──────────┬────────────┬────────┬────────┬──────────┬──────────────┬───────────┬────────┐
|
||
│ 起始符 │ 数据长度 │ 设备地址 │ 预留 │功能码 │ 起始地址 │ 写入数据长度 │ 写入数据 │ CRC-8 │
|
||
│ 0x55AA │ 2B(LE) │ 1B │ 0x00 │ 0x79 │ 4B(LE) │ 2B(LE) │ NB │ 1B │
|
||
├────────┼──────────┼────────────┼────────┼────────┼──────────┼──────────────┼──────────┼────────┤
|
||
│data[0-1]│data[2-3]│ data[4] │data[5] │data[6] │data[7-10]│ data[11-12] │ data[] │data[N+13]│
|
||
└────────┴──────────┴────────────┴────────┴────────┴──────────┴──────────────┴──────────┴────────┘
|
||
```
|
||
|
||
#### 写应答帧
|
||
|
||
```
|
||
┌────────┬──────────┬────────────┬────────┬────────────┬──────────┬───────────┬────────┬────────┐
|
||
│ 起始符 │ 数据长度 │ 设备地址 │ 预留 │ 功能码 │ 起始地址 │ 返回字节数 │ CRC-8 │ 状态 │
|
||
│ 0xAA55 │ 2B(LE) │ 1B │ 0x00 │ 0x80+func │ 4B(LE) │ 2B(LE) │ 1B │ 1B │
|
||
├────────┼──────────┼────────────┼────────┼────────────┼──────────┼───────────┼────────┼────────┤
|
||
│data[0-1]│data[2-3]│ data[4] │data[5] │ data[6] │data[7-10]│data[11-12]│data[14]│data[13]│
|
||
└────────┴──────────┴────────────┴────────┴────────────┴──────────┴───────────┴────────┴────────┘
|
||
```
|
||
|
||
### 2.3 状态码
|
||
|
||
| 值 | 含义 |
|
||
|----|------|
|
||
| `0x0000` | 正常（成功） |
|
||
| `0x0001` | 读取长度超限 |
|
||
| `0x0002` | 长度错误 |
|
||
| `0x0003` | 无效地址 |
|
||
| `0x0004` | 只读寄存器 |
|
||
|
||
### 2.4 功能码
|
||
|
||
| 功能码 | 方向 | 说明 |
|
||
|--------|------|------|
|
||
| `0xFB` | 请求 → | 读请求 |
|
||
| `0x79` | 请求 → | 写请求 |
|
||
| `0x80 + func` | ← 应答 | 读/写应答（`0xFF` = 读应答，`0xF9` = 写应答） |
|
||
|
||
---
|
||
|
||
## 3. 传感器模组布局
|
||
|
||
### 3.1 模组分布（28 个传感器模组）
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ 传感器手套布局 │
|
||
│ │
|
||
│ 大拇指 食指 中指 无名指 小拇指 │
|
||
│ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ │
|
||
│ │指甲│ │指甲│ │指甲│ │指甲│ │指甲│ │
|
||
│ ├──┤ ├──┤ ├──┤ ├──┤ ├──┤ │
|
||
│ │指尖│ │指尖│ │指尖│ │指尖│ │指尖│ │
|
||
│ ├──┤ ├──┤ ├──┤ ├──┤ ├──┤ │
|
||
│ │中节│ │中节│ │中节│ │中节│ │中节│ │
|
||
│ ├──┤ ├──┤ ├──┤ ├──┤ ├──┤ │
|
||
│ │近节│ │近节│ │近节│ │近节│ │近节│ │
|
||
│ └──┘ └──┘ └──┘ └──┘ └──┘ │
|
||
│ │
|
||
│ ┌─────────────────┐ │
|
||
│ │ 掌心 1-8 │ │
|
||
│ │ (8个模组) │ │
|
||
│ └─────────────────┘ │
|
||
└──────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.2 模组编号（0-27）
|
||
|
||
| 编号 | 模组 | 编号 | 模组 |
|
||
|------|------|------|------|
|
||
| 0 | 大拇指-近节 | 14 | 无名指-近节 |
|
||
| 1 | 大拇指-中节 | 15 | 无名指-中节 |
|
||
| 2 | 大拇指-指尖 | 16 | 无名指-指尖 |
|
||
| 3 | 大拇指-指甲 | 17 | 无名指-指甲 |
|
||
| 4 | 食指-近节 | 18 | 小拇指-近节 |
|
||
| 5 | 食指-中节 | 19 | 小拇指-中节 |
|
||
| 6 | 食指-指尖 | 20 | 小拇指-指尖 |
|
||
| 7 | 食指-指甲 | 21 | 小拇指-指甲 |
|
||
| 8 | 中指-近节 | 22 | 掌心 1 |
|
||
| 9 | 中指-中节 | 23 | 掌心 2 |
|
||
| 10 | 中指-指尖 | 24 | 掌心 3 |
|
||
| 11 | 中指-指甲 | 25 | 掌心 4 |
|
||
| 12 | 无名指-近节 | 26 | 掌心 5 |
|
||
| 13 | 无名指-中节 | 27 | 掌心 6 |
|
||
|
||
> 注：掌心 7、掌心 8 为扩展编号 28-29（部分配置可能不包含）。
|
||
|
||
---
|
||
|
||
## 4. 寄存器地址映射
|
||
|
||
### 4.1 系统信息寄存器
|
||
|
||
| 地址 | 名称 | 权限 | 数据类型 | 说明 |
|
||
|------|------|------|---------|------|
|
||
| `0x0000-0x0001` | 系列号 | RO | `u32` | 设备唯一序列号 |
|
||
| `0x000F` | 固件版本 | RO | `u16` | `0x0000` = 系列号，`0x0001` = 软件版本号 |
|
||
| `0x0010` | 标定组 | RO | `u16` | 标定参数组，用于确认产品状态 |
|
||
| `0x0011` | 模组有效状态 | RO | `u16` | bit0-3: 大拇指近/中/指/甲，bit4-7: 食指近/中/指/甲 |
|
||
| `0x0012` | 传感器尺寸 L_LINE | RO | `u16` | 宽度阵列点数 |
|
||
| `0x0013` | 传感器尺寸 H_LINE | RO | `u16` | 长度阵列点数 |
|
||
| `0x0014` | 分布力点数（大拇指） | RO | `u16` | 分布力字节数 = 该值 × 3 |
|
||
| `0x0015` | 分布力点数（食指） | RO | `u16` | 同上 |
|
||
| `0x0016` | 分布力点数（中指） | RO | `u16` | 同上 |
|
||
| `0x0017` | 分布力点数（无名指） | RO | `u16` | 同上 |
|
||
| `0x0018` | 分布力点数（小拇指） | RO | `u16` | 同上 |
|
||
| `0x0023` | 当前模块位置 | RO | `u16` | 0-3: 大拇指，4-7: 食指，... 20-27: 掌心 |
|
||
|
||
### 4.2 配置寄存器
|
||
|
||
| 地址 | 名称 | 权限 | 数据类型 | 说明 |
|
||
|------|------|------|---------|------|
|
||
| `0x0030-0x0031` | 产品配置 1 | RW | `u32` | bit0: 自动回传使能（1=使能，0=不使能，默认0） |
|
||
| `0x0032-0x0033` | 产品配置 2 | RW | `u32` | 保留 |
|
||
| `0x0034-0x003F` | 大拇指分布力点数 | RO | `u16[6]` | 近节、中节、指尖、指甲各模组的分布力点数 |
|
||
| `0x0040-0x004B` | 食指分布力点数 | RO | `u16[6]` | 同上 |
|
||
| `0x004C-0x0057` | 中指分布力点数 | RO | `u16[6]` | 同上 |
|
||
| `0x0058-0x0059` | 无名指分布力点数 | RO | `u16[2]` | 近节、中节 |
|
||
| `0x005A-0x005B` | 无名指分布力点数 | RO | `u16[2]` | 指尖、指甲 |
|
||
| `0x005C-0x0067` | 掌心分布力点数 | RO | `u16[6]` | 掌心8-1（倒序） |
|
||
|
||
### 4.3 数据寄存器
|
||
|
||
| 地址 | 名称 | 权限 | 数据大小 | 说明 |
|
||
|------|------|------|---------|------|
|
||
| `0x0500-0x05A7` | 合力数据 | RO | 168B | 28个模组，每个 3×2B (fx,fy,fz 为 i16) |
|
||
| `0x0700-0x0737` | 模组错误码 | RO | 56B | 28个模组，每个 2B |
|
||
| `0x1000-0x11FF` | 大拇指分布力 | RO | 变长 | 三维分布力 (fx,fy,fz 每点 3B) |
|
||
| `0x1200-0x13FF` | 食指分布力 | RO | 变长 | 同上 |
|
||
| `0x1400-0x15FF` | 中指分布力 | RO | 变长 | 同上 |
|
||
| `0x1600-0x17FF` | 无名指分布力 | RO | 变长 | 同上 |
|
||
| `0x1800-0x19FF` | 小拇指分布力 | RO | 变长 | 同上 |
|
||
| `0x1A00-0x1BFF` | 掌心分布力（1-4） | RO | 变长 | 同上 |
|
||
| `0x1C00-0x1DFF` | 掌心分布力（5-8） | RO | 变长 | 同上 |
|
||
| `0x2000-0x2FFF` | 处理后数值 | RO | 变长 | 原始地址 + 0x3000 |
|
||
| `0x8000-0x8FFF` | 标定参数 | RW | 变长 | 每点 32 参数，最多 128 点 |
|
||
|
||
---
|
||
|
||
## 5. 目录结构
|
||
|
||
```
|
||
eskin-finger-sdk/
|
||
├── Cargo.toml # Rust crate 配置
|
||
├── CMakeLists.txt # C++ wrapper 构建配置
|
||
├── docs/
|
||
│ └── ARCHITECTURE.md # 本文档
|
||
├── include/
|
||
│ └── eskin_finger_sdk.h # C 头文件（公共 API）
|
||
├── cpp/
|
||
│ ├── include/
|
||
│ │ └── eskin_finger_sdk.hpp # C++ wrapper 头文件
|
||
│ └── src/
|
||
│ └── eskin_finger_sdk.cpp # C++ wrapper 实现
|
||
├── src/
|
||
│ ├── lib.rs # Rust 库入口
|
||
│ ├── main.rs # 示例/测试入口
|
||
│ ├── types.rs # 数据建模（传感器结构体、枚举）
|
||
│ ├── error.rs # 错误类型定义
|
||
│ ├── protocol.rs # UART 协议解析（帧编解码、CRC-8-ITU）
|
||
│ ├── transport.rs # 串口传输层（读写抽象）
|
||
│ ├── register.rs # 寄存器地址映射与读写封装
|
||
│ ├── device.rs # 设备管理核心
|
||
│ ├── channel.rs # Channel 设计与管理
|
||
│ ├── stream.rs # 数据流控制（分布力采集）
|
||
│ ├── config.rs # 设备配置管理
|
||
│ └── ffi/
|
||
│ ├── mod.rs # FFI 模块声明
|
||
│ └── c_api.rs # C ABI 实现
|
||
└── examples/
|
||
└── basic_usage.rs # Rust 使用示例
|
||
```
|
||
|
||
---
|
||
|
||
## 6. Crate 依赖 (Cargo.toml)
|
||
|
||
```toml
|
||
[package]
|
||
name = "eskin-finger-sdk"
|
||
version = "0.1.0"
|
||
edition = "2024"
|
||
|
||
[lib]
|
||
name = "eskin_finger_sdk"
|
||
crate-type = ["lib", "cdylib", "staticlib"]
|
||
|
||
[dependencies]
|
||
# Channel 通信 — 高性能多生产者多消费者通道
|
||
crossbeam-channel = "0.5"
|
||
|
||
# 错误处理 — 结构化错误类型
|
||
thiserror = "2"
|
||
|
||
# 日志 — 可选的日志输出
|
||
log = "0.4"
|
||
|
||
# 日志前端
|
||
fern = "0.7"
|
||
|
||
# 时间处理 — 高精度时间戳
|
||
chrono = "0.4"
|
||
|
||
# 序列化 — 配置和数据的序列化支持
|
||
serde = { version = "1", features = ["derive"] }
|
||
serde_json = "1"
|
||
|
||
# FFI 类型支持（C 类型兼容）
|
||
libc = "0.2"
|
||
|
||
# UUID — 设备序列号等唯一标识
|
||
uuid = { version = "1", features = ["v4"] }
|
||
|
||
[dev-dependencies]
|
||
# 测试工具
|
||
env_logger = "0.11"
|
||
```
|
||
|
||
### 依赖说明
|
||
|
||
| 依赖 | 用途 | 必要性 |
|
||
|------|------|--------|
|
||
| `crossbeam-channel` | 高性能 bounded/unbounded channel，支持 `try_send`、`recv_timeout` | **核心** |
|
||
| `thiserror` | 派生 `std::error::Error`，简化错误类型定义 | **核心** |
|
||
| `log` / `fern` | 日志抽象层 + 日志前端，方便调试 | 推荐 |
|
||
| `chrono` | 高精度时间戳（微秒/纳秒级） | 推荐 |
|
||
| `serde` / `serde_json` | 配置文件序列化、调试输出 | 推荐 |
|
||
| `libc` | FFI 类型兼容（`c_char`, `c_int` 等） | **FFI 必需** |
|
||
| `uuid` | 设备唯一标识符生成 | 可选 |
|
||
|
||
### 编译产物
|
||
|
||
```toml
|
||
crate-type = ["lib", "cdylib", "staticlib"]
|
||
```
|
||
|
||
- `lib`：Rust 内部使用
|
||
- `cdylib`：生成 `.dylib`/`.so`/`.dll`，供 C/C++ 动态链接
|
||
- `staticlib`：生成 `.a`/`.lib`，供 C/C++ 静态链接
|
||
|
||
---
|
||
|
||
## 7. 数据建模
|
||
|
||
### 7.1 核心数据类型
|
||
|
||
```rust
|
||
// src/types.rs
|
||
|
||
/// 三维力向量（分布力中的单个测力点）
|
||
#[repr(C)]
|
||
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
|
||
pub struct Force3D {
|
||
pub fx: i16, // X 方向力 (原始值)
|
||
pub fy: i16, // Y 方向力 (原始值)
|
||
pub fz: i16, // Z 方向力 (原始值)
|
||
}
|
||
|
||
/// 三维力向量（浮点版本，用于合力）
|
||
#[repr(C)]
|
||
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
|
||
pub struct Force3F {
|
||
pub fx: f32, // X 方向力 (N)
|
||
pub fy: f32, // Y 方向力 (N)
|
||
pub fz: f32, // Z 方向力 (N)
|
||
}
|
||
|
||
/// 传感器模组标识
|
||
#[repr(C)]
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
|
||
pub enum SensorModule {
|
||
// 大拇指
|
||
ThumbProximal = 0, // 大拇指近节
|
||
ThumbMiddle = 1, // 大拇指中节
|
||
ThumbTip = 2, // 大拇指指尖
|
||
ThumbNail = 3, // 大拇指指甲
|
||
|
||
// 食指
|
||
IndexProximal = 4,
|
||
IndexMiddle = 5,
|
||
IndexTip = 6,
|
||
IndexNail = 7,
|
||
|
||
// 中指
|
||
MiddleProximal = 8,
|
||
MiddleMiddle = 9,
|
||
MiddleTip = 10,
|
||
MiddleNail = 11,
|
||
|
||
// 无名指
|
||
RingProximal = 12,
|
||
RingMiddle = 13,
|
||
RingTip = 14,
|
||
RingNail = 15,
|
||
|
||
// 小拇指
|
||
PinkyProximal = 16,
|
||
PinkyMiddle = 17,
|
||
PinkyTip = 18,
|
||
PinkyNail = 19,
|
||
|
||
// 掌心
|
||
Palm1 = 20,
|
||
Palm2 = 21,
|
||
Palm3 = 22,
|
||
Palm4 = 23,
|
||
Palm5 = 24,
|
||
Palm6 = 25,
|
||
Palm7 = 26,
|
||
Palm8 = 27,
|
||
}
|
||
|
||
/// 单个传感器模组的分布力数据
|
||
#[repr(C)]
|
||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||
pub struct DistributionForce {
|
||
pub module: SensorModule,
|
||
/// 分布力点数（每个点 3 字节: fx, fy, fz）
|
||
pub point_count: u16,
|
||
/// 分布力数据（原始 i8 值，长度 = point_count * 3）
|
||
pub points: Vec<Force3D>,
|
||
}
|
||
|
||
/// 单个传感器模组的合力数据
|
||
#[repr(C)]
|
||
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
|
||
pub struct CombinedForce {
|
||
pub module: SensorModule,
|
||
/// X 方向合力 (i16 原始值)
|
||
pub fx: i16,
|
||
/// Y 方向合力 (i16 原始值)
|
||
pub fy: i16,
|
||
/// Z 方向合力 (i16 原始值)
|
||
pub fz: i16,
|
||
}
|
||
|
||
/// 一帧完整的传感器采样数据
|
||
#[repr(C)]
|
||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||
pub struct FingerSample {
|
||
/// 时间戳（微秒，SDK 侧采集时间）
|
||
pub timestamp_us: u64,
|
||
/// 采样序列号（SDK 侧递增）
|
||
pub sequence: u32,
|
||
/// 28 个模组的合力数据
|
||
pub combined_forces: [CombinedForce; 28],
|
||
/// 28 个模组的分布力数据（可选，根据需求拉取）
|
||
pub distribution_forces: Vec<DistributionForce>,
|
||
/// 28 个模组的错误码（每个模组 2 字节）
|
||
pub module_errors: [u16; 28],
|
||
}
|
||
|
||
/// 单个测力点的简化数据（用于 C ABI 传递分布力）
|
||
#[repr(C)]
|
||
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
|
||
pub struct ForcePoint {
|
||
pub fx: i8,
|
||
pub fy: i8,
|
||
pub fz: i8,
|
||
}
|
||
```
|
||
|
||
### 7.2 设备配置
|
||
|
||
```rust
|
||
// src/config.rs
|
||
|
||
/// 设备配置
|
||
#[repr(C)]
|
||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||
pub struct DeviceConfig {
|
||
/// 设备地址（默认 0x34）
|
||
pub device_addr: u8,
|
||
|
||
/// 是否启用自动回传模式
|
||
/// bit0: 1=使能, 0=不使能（默认0）
|
||
pub auto_transmit: bool,
|
||
|
||
/// 是否读取分布力数据（合力数据始终读取）
|
||
pub read_distribution: bool,
|
||
|
||
/// 样本丢弃策略
|
||
pub drop_policy: DropPolicy,
|
||
}
|
||
|
||
/// 样本丢弃策略
|
||
#[repr(C)]
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub enum DropPolicy {
|
||
/// 丢弃新数据 — 通道满时丢弃当前新样本，保留旧数据
|
||
DropNewest,
|
||
/// 丢弃旧数据 — 通道满时丢弃队列头部的旧数据，保留最新样本
|
||
DropOldest,
|
||
}
|
||
```
|
||
|
||
### 7.3 系统信息
|
||
|
||
```rust
|
||
/// 设备系统信息（从只读寄存器读取）
|
||
#[repr(C)]
|
||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||
pub struct DeviceInfo {
|
||
/// 系列号
|
||
pub serial_number: u32,
|
||
/// 固件版本
|
||
pub firmware_version: u16,
|
||
/// 标定组
|
||
pub calibration_group: u16,
|
||
/// 模组有效状态（bit 掩码）
|
||
pub module_active_status: u16,
|
||
/// 传感器宽度阵列点数 (L_LINE)
|
||
pub l_line: u16,
|
||
/// 传感器长度阵列点数 (H_LINE)
|
||
pub h_line: u16,
|
||
/// 产品配置 1
|
||
pub product_config_1: u32,
|
||
/// 产品配置 2
|
||
pub product_config_2: u32,
|
||
}
|
||
```
|
||
|
||
### 7.4 协议帧类型
|
||
|
||
```rust
|
||
// src/protocol.rs
|
||
|
||
/// 帧起始符
|
||
pub const FRAME_START_REQUEST: u16 = 0x55AA;
|
||
pub const FRAME_START_RESPONSE: u16 = 0xAA55;
|
||
|
||
/// 功能码
|
||
pub const FUNC_READ: u8 = 0xFB;
|
||
pub const FUNC_WRITE: u8 = 0x79;
|
||
pub const FUNC_RESPONSE_READ: u8 = 0xFF; // 0x80 + 0xFB
|
||
pub const FUNC_RESPONSE_WRITE: u8 = 0xF9; // 0x80 + 0x79
|
||
|
||
/// 设备状态码（应答帧中的 status 字段）
|
||
#[repr(C)]
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub enum DeviceStatus {
|
||
Success = 0x0000, // 正常
|
||
ReadLenExceeded = 0x0001, // 读取长度超限
|
||
LengthError = 0x0002, // 长度错误
|
||
InvalidAddress = 0x0003, // 无效地址
|
||
ReadOnlyRegister = 0x0004, // 只读寄存器
|
||
}
|
||
|
||
/// 读请求帧结构
|
||
pub struct ReadRequest {
|
||
pub device_addr: u8,
|
||
pub start_addr: u32,
|
||
pub read_byte_count: u16,
|
||
}
|
||
|
||
/// 写请求帧结构
|
||
pub struct WriteRequest {
|
||
pub device_addr: u8,
|
||
pub start_addr: u32,
|
||
pub data: Vec<u8>,
|
||
}
|
||
|
||
/// 读应答帧结构
|
||
pub struct ReadResponse {
|
||
pub device_addr: u8,
|
||
pub start_addr: u32,
|
||
pub data: Vec<u8>,
|
||
pub status: DeviceStatus,
|
||
}
|
||
|
||
/// 写应答帧结构
|
||
pub struct WriteResponse {
|
||
pub device_addr: u8,
|
||
pub start_addr: u32,
|
||
pub return_byte_count: u16,
|
||
pub status: DeviceStatus,
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 错误处理
|
||
|
||
### 8.1 SDK 错误码（C ABI）
|
||
|
||
```rust
|
||
// src/error.rs
|
||
|
||
/// C ABI 兼容的错误码
|
||
#[repr(C)]
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||
pub enum SdkErrorCode {
|
||
Success = 0,
|
||
InvalidPointer = 1,
|
||
DeviceNotFound = 2,
|
||
DeviceAlreadyOpen = 3,
|
||
NotInitialized = 4,
|
||
AlreadyStreaming = 5,
|
||
NotStreaming = 6,
|
||
ConfigError = 7,
|
||
IoError = 8,
|
||
Timeout = 9,
|
||
ChannelClosed = 10,
|
||
InternalError = 11,
|
||
BufferOverflow = 12,
|
||
InvalidParameter = 13,
|
||
CrcError = 14,
|
||
FrameError = 15,
|
||
ProtocolError = 16,
|
||
DeviceError = 17, // 设备返回非零状态码
|
||
}
|
||
|
||
/// Rust 内部错误类型
|
||
#[derive(Debug, thiserror::Error)]
|
||
pub enum SdkError {
|
||
#[error("Device not found: {0}")]
|
||
DeviceNotFound(String),
|
||
|
||
#[error("Device already open")]
|
||
DeviceAlreadyOpen,
|
||
|
||
#[error("SDK not initialized")]
|
||
NotInitialized,
|
||
|
||
#[error("Already streaming")]
|
||
AlreadyStreaming,
|
||
|
||
#[error("Not streaming")]
|
||
NotStreaming,
|
||
|
||
#[error("Configuration error: {0}")]
|
||
ConfigError(String),
|
||
|
||
#[error("I/O error: {0}")]
|
||
IoError(#[from] std::io::Error),
|
||
|
||
#[error("Read timeout")]
|
||
Timeout,
|
||
|
||
#[error("Channel closed")]
|
||
ChannelClosed,
|
||
|
||
#[error("Internal error: {0}")]
|
||
InternalError(String),
|
||
|
||
#[error("Buffer overflow — dropped {0} samples")]
|
||
BufferOverflow(u64),
|
||
|
||
#[error("Invalid parameter: {0}")]
|
||
InvalidParameter(String),
|
||
|
||
#[error("CRC error: expected 0x{expected:02X}, got 0x{actual:02X}")]
|
||
CrcError { expected: u8, actual: u8 },
|
||
|
||
#[error("Frame error: {0}")]
|
||
FrameError(String),
|
||
|
||
#[error("Protocol error: {0}")]
|
||
ProtocolError(String),
|
||
|
||
#[error("Device error: status 0x{0:04X}")]
|
||
DeviceError(u16),
|
||
}
|
||
```
|
||
|
||
### 8.2 设备侧错误码
|
||
|
||
```rust
|
||
/// 设备应答帧中的状态码
|
||
impl DeviceStatus {
|
||
pub fn to_error(&self) -> Option<SdkError> {
|
||
match self {
|
||
DeviceStatus::Success => None,
|
||
DeviceStatus::ReadLenExceeded => Some(SdkError::DeviceError(0x0001)),
|
||
DeviceStatus::LengthError => Some(SdkError::DeviceError(0x0002)),
|
||
DeviceStatus::InvalidAddress => Some(SdkError::DeviceError(0x0003)),
|
||
DeviceStatus::ReadOnlyRegister => Some(SdkError::DeviceError(0x0004)),
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. CRC-8-ITU 校验
|
||
|
||
```rust
|
||
// src/protocol.rs
|
||
|
||
/// CRC-8-ITU 多项式: x^8 + x^2 + x + 1 (0x07)
|
||
/// 初始值: 0x00
|
||
pub fn crc8_itu(data: &[u8]) -> u8 {
|
||
let mut crc: u8 = 0x00;
|
||
for &byte in data {
|
||
crc ^= byte;
|
||
for _ in 0..8 {
|
||
if crc & 0x80 != 0 {
|
||
crc = (crc << 1) ^ 0x07;
|
||
} else {
|
||
crc <<= 1;
|
||
}
|
||
}
|
||
}
|
||
crc
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 10. Channel 设计
|
||
|
||
### 10.1 通道架构
|
||
|
||
```
|
||
┌──────────────────────┐
|
||
│ UART I/O Thread │
|
||
│ (串口数据采集线程) │
|
||
└──────┬───────┬───────┘
|
||
│ │
|
||
sample_tx event_tx
|
||
│ │
|
||
┌────────────▼─┐ ┌──▼───────────┐
|
||
│ Data Channel │ │ Event Channel │
|
||
│ (bounded) │ │ (bounded) │
|
||
│ capacity: 64 │ │ capacity: 64 │
|
||
└────────────┬─┘ └──┬────────────┘
|
||
│ │
|
||
sample_rx event_rx
|
||
│ │
|
||
┌────────────▼───────▼────────────┐
|
||
│ User-facing API │
|
||
│ read_sample() / callback │
|
||
└──────────────────────────────────┘
|
||
|
||
┌──────────────────────┐
|
||
│ User Thread │
|
||
└──────┬───────────────┘
|
||
│
|
||
cmd_tx
|
||
│
|
||
┌──────▼──────────────┐
|
||
│ Command Channel │
|
||
│ (bounded) │
|
||
│ capacity: 16 │
|
||
└──────┬───────────────┘
|
||
│
|
||
cmd_rx
|
||
┌──────▼──────────────┐
|
||
│ UART I/O Thread │
|
||
└──────────────────────┘
|
||
```
|
||
|
||
### 10.2 通道定义
|
||
|
||
```rust
|
||
// src/channel.rs
|
||
|
||
use crossbeam_channel::{bounded, Sender, Receiver};
|
||
use std::sync::atomic::{AtomicU64, Ordering};
|
||
|
||
/// 设备命令
|
||
#[derive(Debug, Clone)]
|
||
pub enum DeviceCommand {
|
||
StartStream,
|
||
StopStream,
|
||
SetConfig(DeviceConfig),
|
||
/// 读取指定寄存器
|
||
ReadRegister { addr: u32, length: u16 },
|
||
/// 写入指定寄存器
|
||
WriteRegister { addr: u32, data: Vec<u8> },
|
||
Shutdown,
|
||
}
|
||
|
||
/// 设备事件
|
||
#[derive(Debug, Clone)]
|
||
pub enum DeviceEvent {
|
||
Disconnected(String),
|
||
IoError(String),
|
||
ProtocolError(String),
|
||
ConfigApplied,
|
||
StreamStarted,
|
||
StreamStopped,
|
||
SampleDropped { count: u64 },
|
||
ModuleError { module: SensorModule, error_code: u16 },
|
||
}
|
||
|
||
/// 通道管理器
|
||
pub struct ChannelManager {
|
||
// 数据通道 — 传感器采样数据
|
||
pub sample_tx: Sender<FingerSample>,
|
||
pub sample_rx: Receiver<FingerSample>,
|
||
|
||
// 命令通道 — 控制命令
|
||
pub cmd_tx: Sender<DeviceCommand>,
|
||
pub cmd_rx: Receiver<DeviceCommand>,
|
||
|
||
// 事件通道 — 事件通知
|
||
pub event_tx: Sender<DeviceEvent>,
|
||
pub event_rx: Receiver<DeviceEvent>,
|
||
|
||
// 丢弃计数器
|
||
pub dropped_samples: AtomicU64,
|
||
|
||
// 丢弃策略
|
||
pub drop_policy: DropPolicy,
|
||
}
|
||
|
||
impl ChannelManager {
|
||
pub fn new(
|
||
sample_capacity: usize, // 建议 64（传感器帧率较低）
|
||
cmd_capacity: usize, // 建议 16
|
||
event_capacity: usize, // 建议 64
|
||
drop_policy: DropPolicy,
|
||
) -> Self {
|
||
let (sample_tx, sample_rx) = bounded(sample_capacity);
|
||
let (cmd_tx, cmd_rx) = bounded(cmd_capacity);
|
||
let (event_tx, event_rx) = bounded(event_capacity);
|
||
|
||
Self {
|
||
sample_tx, sample_rx,
|
||
cmd_tx, cmd_rx,
|
||
event_tx, event_rx,
|
||
dropped_samples: AtomicU64::new(0),
|
||
drop_policy,
|
||
}
|
||
}
|
||
|
||
/// 非阻塞发送样本，根据策略处理溢出
|
||
pub fn send_sample(&self, sample: FingerSample) {
|
||
match self.drop_policy {
|
||
DropPolicy::DropNewest => {
|
||
if self.sample_tx.try_send(sample).is_err() {
|
||
self.dropped_samples.fetch_add(1, Ordering::Relaxed);
|
||
}
|
||
}
|
||
DropPolicy::DropOldest => {
|
||
if let Err(crossbeam_channel::TrySendError::Full(_)) =
|
||
self.sample_tx.try_send(sample)
|
||
{
|
||
let _ = self.sample_rx.try_recv();
|
||
if self.sample_tx.try_send(sample).is_err() {
|
||
self.dropped_samples.fetch_add(1, Ordering::Relaxed);
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
/// 带超时的样本读取
|
||
pub fn recv_sample(&self, timeout_ms: u32) -> Result<FingerSample, SdkError> {
|
||
let timeout = std::time::Duration::from_millis(timeout_ms as u64);
|
||
self.sample_rx
|
||
.recv_timeout(timeout)
|
||
.map_err(|_| SdkError::Timeout)
|
||
}
|
||
|
||
/// 获取丢弃的样本数量
|
||
pub fn dropped_count(&self) -> u64 {
|
||
self.dropped_samples.load(Ordering::Relaxed)
|
||
}
|
||
}
|
||
```
|
||
|
||
### 10.3 通道容量配置
|
||
|
||
| 通道 | 容量 | 频率 | 说明 |
|
||
|------|------|------|------|
|
||
| 数据通道 (sample) | 64 | 低频 (~10-100Hz) | bounded，传感器帧率决定 |
|
||
| 命令通道 (cmd) | 16 | 低频 (~1Hz) | bounded，固定 |
|
||
| 事件通道 (event) | 64 | 低频 (~1Hz) | bounded，固定 |
|
||
|
||
---
|
||
|
||
## 11. 设备管理
|
||
|
||
### 11.1 设备状态机
|
||
|
||
```
|
||
┌──────────┐ init() ┌──────────────┐
|
||
│ Idle │ ──────────────►│ Initialized │
|
||
└──────────┘ └──────┬───────┘
|
||
▲ │
|
||
│ open(port)
|
||
│ │
|
||
│ ┌────▼───────┐
|
||
│ │ Connected │
|
||
│ └────┬───────┘
|
||
│ │
|
||
│ start_stream()
|
||
│ │
|
||
│ ┌────▼───────┐
|
||
│ │ Streaming │
|
||
│ └────┬───────┘
|
||
│ │
|
||
│ stop_stream()
|
||
│ │
|
||
│ ┌────▼───────┐
|
||
│ close() │ Connected │
|
||
│◄───────────────────────└────────────┘
|
||
│
|
||
shutdown()
|
||
```
|
||
|
||
### 11.2 核心设备结构
|
||
|
||
```rust
|
||
// src/device.rs
|
||
|
||
pub struct EskinDeviceInner {
|
||
pub info: DeviceInfo,
|
||
pub config: DeviceConfig,
|
||
pub channels: ChannelManager,
|
||
pub state: DeviceState,
|
||
pub transport: Box<dyn SerialTransport>,
|
||
pub stream_handle: Option<JoinHandle<()>>,
|
||
pub cmd_handle: Option<JoinHandle<()>>,
|
||
pub shutdown_flag: Arc<AtomicBool>,
|
||
pub sequence_counter: AtomicU32,
|
||
}
|
||
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||
pub enum DeviceState {
|
||
Idle,
|
||
Initialized,
|
||
Connected,
|
||
Streaming,
|
||
Error,
|
||
}
|
||
```
|
||
|
||
### 11.3 传输层抽象
|
||
|
||
```rust
|
||
// src/transport.rs
|
||
|
||
/// 串口传输抽象（方便测试时 mock）
|
||
pub trait SerialTransport: Send + Sync {
|
||
/// 发送原始字节
|
||
fn write(&mut self, data: &[u8]) -> Result<usize, SdkError>;
|
||
/// 接收原始字节（带超时）
|
||
fn read(&mut self, buf: &mut [u8], timeout: Duration) -> Result<usize, SdkError>;
|
||
/// 清空接收缓冲区
|
||
fn flush_rx(&mut self) -> Result<(), SdkError>;
|
||
}
|
||
|
||
/// 真实串口实现
|
||
pub struct SerialPortTransport {
|
||
port: Box<dyn serialport::SerialPort>,
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 12. 数据采集流程
|
||
|
||
### 12.1 合力数据采集（标准模式）
|
||
|
||
```
|
||
用户调用 start_stream()
|
||
│
|
||
▼
|
||
┌──────────────────────────────────────────┐
|
||
│ UART I/O Thread 启动 │
|
||
│ │
|
||
│ loop { │
|
||
│ 1. 检查 shutdown_flag │
|
||
│ 2. 检查 cmd_rx 是否有新命令 │
|
||
│ 3. 发送读请求: 0x0500, 长度 168 字节 │
|
||
│ (28 模组 × 6 字节合力) │
|
||
│ 4. 接收读应答帧 │
|
||
│ 5. 校验 CRC-8-ITU │
|
||
│ 6. 解析 28 个 CombinedForce │
|
||
│ 7. 组装 FingerSample │
|
||
│ 8. sample_tx.try_send(sample) │
|
||
│ 9. 如果配置了 read_distribution: │
|
||
│ a. 依次发送读请求获取各指分布力 │
|
||
│ b. 填充 distribution_forces │
|
||
│ } │
|
||
└──────────────────────────────────────────┘
|
||
```
|
||
|
||
### 12.2 分布力数据采集
|
||
|
||
分布力数据按模组分段读取，每段地址范围不同：
|
||
|
||
| 传感器 | 地址范围 | 每点字节数 |
|
||
|--------|---------|-----------|
|
||
| 大拇指 | `0x1000-0x11FF` | 3 (fx, fy, fz) |
|
||
| 食指 | `0x1200-0x13FF` | 3 |
|
||
| 中指 | `0x1400-0x15FF` | 3 |
|
||
| 无名指 | `0x1600-0x17FF` | 3 |
|
||
| 小拇指 | `0x1800-0x19FF` | 3 |
|
||
| 掌心 1-4 | `0x1A00-0x1BFF` | 3 |
|
||
| 掌心 5-8 | `0x1C00-0x1DFF` | 3 |
|
||
|
||
> 分布力字节数 = point_count × 3，point_count 从 `0x0014-0x0018` 等寄存器读取。
|
||
|
||
### 12.3 命令处理流程
|
||
|
||
```
|
||
cmd_rx 接收到命令
|
||
│
|
||
▼
|
||
match command {
|
||
StartStream → 设置 streaming 标志，开始采集循环
|
||
StopStream → 清除 streaming 标志
|
||
SetConfig(cfg) → 写入产品配置寄存器 (0x0030)
|
||
ReadRegister → 发送读请求，返回结果
|
||
WriteRegister → 发送写请求，检查状态码
|
||
Shutdown → 设置 shutdown_flag，退出线程
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 13. C ABI 设计
|
||
|
||
### 13.1 Opaque Pointer 模式
|
||
|
||
```rust
|
||
// src/ffi/c_api.rs
|
||
|
||
/// 不透明指针，C 端只能通过 API 函数操作
|
||
#[repr(C)]
|
||
pub struct EskinDevice {
|
||
inner: Box<EskinDeviceInner>,
|
||
}
|
||
|
||
/// 全局 SDK 状态
|
||
static SDK_STATE: OnceLock<Mutex<SdkState>> = OnceLock::new();
|
||
|
||
struct SdkState {
|
||
initialized: bool,
|
||
}
|
||
```
|
||
|
||
### 13.2 C API 函数签名
|
||
|
||
```c
|
||
// include/eskin_finger_sdk.h
|
||
|
||
#ifndef ESKIN_FINGER_SDK_H
|
||
#define ESKIN_FINGER_SDK_H
|
||
|
||
#include <stdint.h>
|
||
#include <stddef.h>
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
// ─── 错误码 ──────────────────────────────────────────
|
||
typedef enum {
|
||
ESKIN_SUCCESS = 0,
|
||
ESKIN_INVALID_POINTER = 1,
|
||
ESKIN_DEVICE_NOT_FOUND = 2,
|
||
ESKIN_DEVICE_ALREADY_OPEN = 3,
|
||
ESKIN_NOT_INITIALIZED = 4,
|
||
ESKIN_ALREADY_STREAMING = 5,
|
||
ESKIN_NOT_STREAMING = 6,
|
||
ESKIN_CONFIG_ERROR = 7,
|
||
ESKIN_IO_ERROR = 8,
|
||
ESKIN_TIMEOUT = 9,
|
||
ESKIN_CHANNEL_CLOSED = 10,
|
||
ESKIN_INTERNAL_ERROR = 11,
|
||
ESKIN_BUFFER_OVERFLOW = 12,
|
||
ESKIN_INVALID_PARAMETER = 13,
|
||
ESKIN_CRC_ERROR = 14,
|
||
ESKIN_FRAME_ERROR = 15,
|
||
ESKIN_PROTOCOL_ERROR = 16,
|
||
ESKIN_DEVICE_ERROR = 17,
|
||
} EskinErrorCode;
|
||
|
||
// ─── 数据类型 ────────────────────────────────────────
|
||
typedef struct { int16_t fx, fy, fz; } EskinForce3D;
|
||
|
||
typedef struct {
|
||
uint8_t module_index; // 0-27
|
||
int16_t fx, fy, fz;
|
||
} EskinCombinedForce;
|
||
|
||
typedef struct {
|
||
uint8_t module_index;
|
||
uint16_t point_count;
|
||
EskinForce3D* points; // 长度 = point_count
|
||
} EskinDistributionForce;
|
||
|
||
typedef struct {
|
||
uint64_t timestamp_us;
|
||
uint32_t sequence;
|
||
EskinCombinedForce combined_forces[28];
|
||
EskinDistributionForce* distribution_forces; // 可选，NULL 表示不采集
|
||
uint16_t distribution_count;
|
||
uint16_t module_errors[28];
|
||
} EskinSample;
|
||
|
||
typedef struct {
|
||
uint32_t serial_number;
|
||
uint16_t firmware_version;
|
||
uint16_t calibration_group;
|
||
uint16_t module_active_status;
|
||
uint16_t l_line;
|
||
uint16_t h_line;
|
||
uint32_t product_config_1;
|
||
uint32_t product_config_2;
|
||
} EskinDeviceInfo;
|
||
|
||
typedef enum {
|
||
ESKIN_DROP_NEWEST = 0,
|
||
ESKIN_DROP_OLDEST = 1,
|
||
} EskinDropPolicy;
|
||
|
||
typedef struct {
|
||
uint8_t device_addr; // 默认 0x34
|
||
int auto_transmit; // 0=不使能, 1=使能
|
||
int read_distribution; // 0=只读合力, 1=也读分布力
|
||
EskinDropPolicy drop_policy;
|
||
} EskinConfig;
|
||
|
||
// ─── 设备管理 API ────────────────────────────────────
|
||
EskinErrorCode eskin_initialize(void);
|
||
EskinErrorCode eskin_shutdown(void);
|
||
|
||
EskinErrorCode eskin_open(const char* port_name, EskinDevice** out_device);
|
||
EskinErrorCode eskin_open_by_serial(const char* serial, EskinDevice** out_device);
|
||
void eskin_close(EskinDevice* device);
|
||
|
||
// ─── 设备信息 API ────────────────────────────────────
|
||
EskinErrorCode eskin_get_device_info(EskinDevice* device, EskinDeviceInfo* out_info);
|
||
|
||
// ─── 配置 API ────────────────────────────────────────
|
||
EskinErrorCode eskin_get_config(EskinDevice* device, EskinConfig* config);
|
||
EskinErrorCode eskin_set_config(EskinDevice* device, const EskinConfig* config);
|
||
|
||
// ─── 流控制 API ──────────────────────────────────────
|
||
EskinErrorCode eskin_start_stream(EskinDevice* device);
|
||
EskinErrorCode eskin_stop_stream(EskinDevice* device);
|
||
|
||
// ─── 数据读取 API ────────────────────────────────────
|
||
EskinErrorCode eskin_read_sample(EskinDevice* device, EskinSample* out_sample,
|
||
uint32_t timeout_ms);
|
||
uint64_t eskin_get_dropped_sample_count(EskinDevice* device);
|
||
|
||
// ─── 寄存器直接访问 API ─────────────────────────────
|
||
EskinErrorCode eskin_read_register(EskinDevice* device, uint32_t addr,
|
||
uint16_t length, uint8_t* out_data);
|
||
EskinErrorCode eskin_write_register(EskinDevice* device, uint32_t addr,
|
||
uint16_t length, const uint8_t* data);
|
||
|
||
// ─── 错误管理 API ────────────────────────────────────
|
||
const char* eskin_error_string(EskinErrorCode code);
|
||
EskinErrorCode eskin_get_last_error(EskinDevice* device);
|
||
|
||
// ─── 内存管理 API ────────────────────────────────────
|
||
void eskin_free_sample(EskinSample* sample);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif // ESKIN_FINGER_SDK_H
|
||
```
|
||
|
||
---
|
||
|
||
## 14. C++ Wrapper 设计
|
||
|
||
### 14.1 RAII 封装
|
||
|
||
```cpp
|
||
// cpp/include/eskin_finger_sdk.hpp
|
||
|
||
#pragma once
|
||
|
||
#include "eskin_finger_sdk.h"
|
||
#include <functional>
|
||
#include <stdexcept>
|
||
#include <string>
|
||
#include <thread>
|
||
#include <atomic>
|
||
#include <vector>
|
||
#include <array>
|
||
|
||
namespace eskin {
|
||
|
||
// ─── 异常类型 ────────────────────────────────────────
|
||
class EskinException : public std::runtime_error {
|
||
public:
|
||
EskinException(EskinErrorCode code, const std::string& msg)
|
||
: std::runtime_error(msg), code_(code) {}
|
||
EskinErrorCode code() const { return code_; }
|
||
private:
|
||
EskinErrorCode code_;
|
||
};
|
||
|
||
// ─── 数据类型 ────────────────────────────────────────
|
||
struct Force3D { int16_t fx, fy, fz; };
|
||
|
||
struct CombinedForce {
|
||
uint8_t module_index;
|
||
int16_t fx, fy, fz;
|
||
};
|
||
|
||
struct DistributionForce {
|
||
uint8_t module_index;
|
||
std::vector<Force3D> points;
|
||
};
|
||
|
||
struct Sample {
|
||
uint64_t timestamp_us;
|
||
uint32_t sequence;
|
||
std::array<CombinedForce, 28> combined_forces;
|
||
std::vector<DistributionForce> distribution_forces;
|
||
std::array<uint16_t, 28> module_errors;
|
||
};
|
||
|
||
struct DeviceInfo {
|
||
uint32_t serial_number;
|
||
uint16_t firmware_version;
|
||
uint16_t calibration_group;
|
||
uint16_t module_active_status;
|
||
uint16_t l_line;
|
||
uint16_t h_line;
|
||
};
|
||
|
||
// ─── 回调类型 ────────────────────────────────────────
|
||
using SampleCallback = std::function<void(const Sample&)>;
|
||
using ErrorCallback = std::function<void(EskinErrorCode, const std::string&)>;
|
||
|
||
// ─── RAII Device 封装 ────────────────────────────────
|
||
class Device {
|
||
public:
|
||
Device(const Device&) = delete;
|
||
Device& operator=(const Device&) = delete;
|
||
Device(Device&& other) noexcept;
|
||
Device& operator=(Device&& other) noexcept;
|
||
~Device();
|
||
|
||
// 设备信息
|
||
DeviceInfo getDeviceInfo();
|
||
|
||
// 配置
|
||
void setConfig(const EskinConfig& config);
|
||
EskinConfig getConfig();
|
||
|
||
// 流控制
|
||
void start();
|
||
void stop();
|
||
|
||
// 同步数据读取
|
||
Sample readSample(uint32_t timeout_ms = 1000);
|
||
uint64_t getDroppedSampleCount() const;
|
||
|
||
// 寄存器直接访问
|
||
std::vector<uint8_t> readRegister(uint32_t addr, uint16_t length);
|
||
void writeRegister(uint32_t addr, const std::vector<uint8_t>& data);
|
||
|
||
// 回调模式
|
||
void setCallback(SampleCallback on_sample);
|
||
void setErrorCallback(ErrorCallback on_error);
|
||
void startAsync();
|
||
void stopAsync();
|
||
|
||
private:
|
||
friend class Sdk;
|
||
explicit Device(EskinDevice* handle);
|
||
|
||
EskinDevice* handle_ = nullptr;
|
||
SampleCallback sample_callback_;
|
||
ErrorCallback error_callback_;
|
||
std::thread callback_thread_;
|
||
std::atomic<bool> callback_running_{false};
|
||
};
|
||
|
||
// ─── SDK 全局管理 ────────────────────────────────────
|
||
class Sdk {
|
||
public:
|
||
Sdk();
|
||
~Sdk();
|
||
|
||
Sdk(const Sdk&) = delete;
|
||
Sdk& operator=(const Sdk&) = delete;
|
||
|
||
Device open(const std::string& port_name);
|
||
Device openBySerial(const std::string& serial);
|
||
|
||
static std::string errorString(EskinErrorCode code);
|
||
|
||
private:
|
||
bool initialized_ = false;
|
||
};
|
||
|
||
} // namespace eskin
|
||
```
|
||
|
||
---
|
||
|
||
## 15. 数据流示意
|
||
|
||
### 15.1 同步读取模式（Pull）
|
||
|
||
```
|
||
用户线程 SDK 内部
|
||
│ │
|
||
│ eskin_read_sample() │
|
||
│────────────────────────────►│ sample_rx.recv_timeout()
|
||
│ │
|
||
│ 内部循环: │
|
||
│ 1. 发送 UART 读请求 │
|
||
│ 2. 接收应答，校验 CRC │
|
||
│ 3. 解析合力/分布力 │
|
||
│ 4. 组装 FingerSample │
|
||
│ 5. 通过 channel 传递 │
|
||
│ │
|
||
│◄────────────────────────────│ 返回 FingerSample 或 Timeout
|
||
│ │
|
||
│ eskin_get_dropped_count() │
|
||
│────────────────────────────►│ atomic load
|
||
│◄────────────────────────────│ 返回 u64
|
||
```
|
||
|
||
### 15.2 回调模式（Push）
|
||
|
||
```
|
||
SDK 内部 用户回调
|
||
│ │
|
||
│ UART I/O 线程采集并解析 │
|
||
│ sample_tx.try_send(sample) │
|
||
│ │
|
||
│ 回调线程 recv sample │
|
||
│────────────────────────────────►│ on_sample(sample)
|
||
│ │
|
||
│ 如果采集出错 │
|
||
│────────────────────────────────►│ on_error(code, msg)
|
||
```
|
||
|
||
---
|
||
|
||
## 16. 线程模型
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ Rust SDK 进程 │
|
||
│ │
|
||
│ ┌───────────────────┐ ┌───────────────────┐ │
|
||
│ │ UART I/O Thread │ │ Command Handler │ │
|
||
│ │ (per device) │ │ (same thread) │ │
|
||
│ │ │ │ │ │
|
||
│ │ - 串口读写 │ │ - 接收 cmd_rx │ │
|
||
│ │ - CRC 校验 │ │ - 执行寄存器操作 │ │
|
||
│ │ - 协议解析 │ │ - 写入设备 │ │
|
||
│ │ - 组装样本 │ │ │ │
|
||
│ │ - sample_tx │ │ │ │
|
||
│ │ - event_tx │ │ │ │
|
||
│ └───────┬───────────┘ └───────┬───────────┘ │
|
||
│ │ │ │
|
||
│ ▼ ▼ │
|
||
│ ┌───────────────────────────────────────┐ │
|
||
│ │ Channel Manager │ │
|
||
│ │ - sample channel (bounded 64) │ │
|
||
│ │ - cmd channel (bounded 16) │ │
|
||
│ │ - event channel (bounded 64) │ │
|
||
│ │ - dropped_samples (AtomicU64) │ │
|
||
│ └───────────────────┬───────────────────┘ │
|
||
│ │ │
|
||
│ ┌───────────────────▼───────────────────┐ │
|
||
│ │ User-facing API │ │
|
||
│ │ - C ABI (extern "C") │ │
|
||
│ │ - C++ Wrapper (RAII + callback) │ │
|
||
│ └───────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 17. 关键设计决策
|
||
|
||
| 决策 | 选择 | 理由 |
|
||
|------|------|------|
|
||
| Channel 库 | `crossbeam-channel` | 比 `std::sync::mpsc` 更高性能，支持 MPMC，有 `try_send`、`recv_timeout` |
|
||
| 数据通道容量 | 64 (bounded) | 传感器帧率较低 (~10-100Hz)，64 帧缓冲足够 |
|
||
| 样本发送策略 | `try_send` (非阻塞) | 采集线程绝不阻塞，保证实时性 |
|
||
| 丢弃策略 | 可配置 (`DropNewest`/`DropOldest`) | 不同场景需求不同 |
|
||
| FFI 指针 | Opaque pointer (`EskinDevice*`) | 隐藏内部结构，ABI 稳定 |
|
||
| 内存管理 | Box + raw pointer | Rust 侧 Box 管理，C 侧只持有指针，`close()` 时归还 |
|
||
| 错误处理 | 错误码 + last_error | C ABI 用错误码，C++ wrapper 转为异常 |
|
||
| 时间戳 | `u64` 微秒 | SDK 侧采集时间，避免浮点精度问题 |
|
||
| CRC 校验 | CRC-8-ITU | 协议规定，多项式 0x07，初始值 0x00 |
|
||
| 传输抽象 | `SerialTransport` trait | 方便单元测试 mock，可扩展支持其他传输方式 |
|
||
| 分布力采集 | 可选配置 | 分布力数据量大，按需采集避免影响帧率 |
|
||
|
||
---
|
||
|
||
## 18. 指令示例
|
||
|
||
### 18.1 读取固件版本信息
|
||
|
||
```
|
||
请求: 55 AA 09 00 34 00 FB 00 00 00 00 10 00 76
|
||
├─起始─┤├─长度─┤├地址┤├─功能─┤├─地址──┤├─长度──┤├CRC┤
|
||
|
||
应答: AA 55 09 00 34 00 FF 00 00 00 00 02 00 xx xx CRC 00
|
||
```
|
||
|
||
### 18.2 读取大拇指指尖分布力点数
|
||
|
||
```
|
||
请求: 55 AA 09 00 34 00 FB 14 00 00 00 02 00 31
|
||
起始地址 = 0x0014, 读取 2 字节
|
||
```
|
||
|
||
### 18.3 读取食指指尖合力
|
||
|
||
```
|
||
请求: 55 AA 09 00 34 00 FB 00 1C 00 00 A8 00 35
|
||
起始地址 = 0x1C00, 读取 0xA8 = 168 字节
|
||
```
|
||
|
||
### 18.4 修改食指指尖 L_LINE 值
|
||
|
||
```
|
||
写请求: 55 AA 0A 00 34 00 79 14 00 00 00 01 00 03 A4
|
||
起始地址 = 0x0014, 写入 1 字节, 数据 = 0x03
|
||
```
|
||
|
||
---
|
||
|
||
## 19. 构建方式
|
||
|
||
### Rust（生成 C 共享库）
|
||
|
||
```bash
|
||
cargo build --release
|
||
# 产物: target/release/libeskin_finger_sdk.dylib (macOS)
|
||
# target/release/libeskin_finger_sdk.so (Linux)
|
||
# target/release/eskin_finger_sdk.dll (Windows)
|
||
```
|
||
|
||
### C++ Wrapper（CMake）
|
||
|
||
```bash
|
||
mkdir build && cd build
|
||
cmake ..
|
||
make
|
||
```
|
||
|
||
### Python 绑定（未来扩展）
|
||
|
||
可以通过 `cffi` 或 `pybind11` 直接加载 C 共享库，无需额外绑定层。
|
||
|
||
---
|
||
|
||
## 20. 安全性考虑
|
||
|
||
1. **空指针检查**：所有 C API 入口检查指针非空
|
||
2. **状态检查**：操作前检查设备状态（是否已连接、是否正在采集等）
|
||
3. **CRC 校验**：每帧数据必须通过 CRC-8-ITU 校验
|
||
4. **帧完整性**：检查起始符、数据长度与实际数据一致性
|
||
5. **线程安全**：使用 `AtomicBool`、`AtomicU64`、`AtomicU32` 管理共享状态
|
||
6. **资源泄漏**：C++ RAII 保证析构时释放；C API 提供 `eskin_close()`
|
||
7. **panic 安全**：Rust FFI 函数不 panic，所有 panic 用 `catch_unwind` 捕获
|
||
8. **超时保护**：所有串口读操作带超时，避免永久阻塞 |