修复粘包问题

- Change CForce3D fx/fy/fz from int16 to uint32 to match hardware
- Add independent C++ example with command and streaming modes
- Rewrite Python example with threaded streaming (read_loop + consumer pattern)
- Add ROS2 C++ publisher/subscriber examples
- Update README with streaming APIs, ROS2 docs, data type definitions, and full FFI table
- Add CHANGELOG

CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+## v0.1.0 (2026-05-07)
+
+E-Skin 手指力传感器 SDK 首个正式版本，支持 Rust / C/C++ / Python 多语言调用。
+
+### ✨ 核心功能
+
+- **串口通信**：基于 `serialport` 的串口传输层，支持 UART 连接
+- **协议编解码**：完整的请求/响应帧编解码，内置 CRC-8/X25 校验
+- **寄存器读写**：底层寄存器原始字节读写接口
+- **设备配置管理**：硬件版本读取、矩阵行列尺寸读写、设备配置寄存器读写
+- **流式采集**：基于 `crossbeam-channel` 的高性能线程间数据传输
+- **设备管理**：设备打开/关闭状态机，支持 Open / Streaming / Error 状态
+
+### 🔌 FFI 接口
+
+提供完整的 C FFI 导出，支持 C/C++ 和 Python 调用：
+
+| 接口 | 说明 |
+|------|------|
+| `eskin_version` | SDK 版本 |
+| `eskin_open` / `eskin_close` | 设备打开/关闭 |
+| `eskin_read_register` / `eskin_write_register` | 寄存器原始读写 |
+| `eskin_read_hdw_version` | 硬件版本号 |
+| `eskin_read_matrix_row` / `col` | 矩阵行列读取 |
+| `eskin_write_matrix_row` / `col` | 矩阵行列写入 |
+| `eskin_read_device_config1` / `2` | 设备配置寄存器读取 |
+| `eskin_write_device_config1` / `2` | 设备配置寄存器写入 |
+
+### 📦 示例代码
+
+- **C++ 示例**：`example/cpp/main.cpp`
+- **Python 示例**：`example/python/example.py` + `example/python/eskin_ffi.py`
+
+### 🛠 构建
+
+```bash
+# 安装依赖（Ubuntu）
+sudo apt install pkg-config libudev-dev
+
+# 构建
+cargo build --release
+# 输出: target/release/libeskin_finger_sdk.so
+```
+
+### 📋 协议
+
+- 请求帧：`[0x55, 0xAA] + data_len(LE) + dev_addr + func + addr(LE) + len(LE) + payload + crc8`
+- 响应帧：同上格式 + status 字段，`0x00` 表示成功
+- 支持功能码：`READ=0xFB`、`WRITE=0x79`、`RESPONSE_READ=0xFF`、`RESPONSE_WRITE=0xF9`
+
+### ⚠️ 已知限制
+
+- 当前仅支持串口传输（UART）
+- 版本号 `0.1.0`，API 可能在后续版本中调整

README.md

@@ -1,6 +1,6 @@
 # Eskin Finger SDK
 
-E-Skin 手指力传感器 Rust SDK，提供串口通信、寄存器读写、流式采集能力，支持 Rust / C/C++ / Python 调用。
+E-Skin 手指力传感器 Rust SDK，提供串口通信、寄存器读写、流式采集能力，支持 Rust / C/C++ / Python / ROS2 调用。
 
 ## 目录结构
 
@@ -22,8 +22,10 @@ include/
   eskin_ffi.h     — C/C++ 头文件
 
 example/
-  cpp/main.cpp    — C++ 使用示例
+  cpp/main.cpp       — 独立 C++ 使用示例（含流式采集）
-  python/         — Python 使用示例
+  python/eskin_ffi.py — Python FFI 包装器
+  python/example.py   — Python 使用示例（含流式采集）
+  ros-cpp/            — ROS2 C++ 示例（publisher/subscriber）
 ```
 
 ---
@@ -51,6 +53,20 @@ println!("Wrote {} bytes", count);
 device.close().unwrap();
 ```
 
+### 流式采集（Rust）
+
+```rust
+// 启动流式采集
+device.start_stream().unwrap();
+
+// 读取采样数据
+let sample = device.read_sample(Some(std::time::Duration::from_millis(200))).unwrap();
+println!("force: fx={} fy={} fz={}", sample.force.fx, sample.force.fy, sample.force.fz);
+
+// 停止采集
+device.stop_stream().unwrap();
+```
+
 ---
 
 ## 使用 C/C++
@@ -69,26 +85,46 @@ cargo build --release
 ### 编译 C++ 示例
 
 ```bash
-g++ example/cpp/main.cpp -I include -L target/release -leskin_finger_sdk -o example_cpp
+g++ -std=c++17 example/cpp/main.cpp -I include -L target/release -leskin_finger_sdk -lpthread -o example_cpp
 LD_LIBRARY_PATH=target/release ./example_cpp
 ```
 
 ### C++ 代码示例
 
+完整示例见 `example/cpp/main.cpp`，包含 Command 模式和 Streaming 模式：
+
 ```cpp
 #include "eskin_ffi.h"
 #include <cstdio>
+#include <cstring>
+#include <thread>
+#include <mutex>
+#include <queue>
 
 int main() {
+    // 打开设备
     EskinDeviceHandle dev = eskin_open("/dev/ttyUSB0", nullptr);
     if (!dev) return 1;
 
-    uint8_t buf[256];
+    // Command 模式：读取设备信息
-    uint32_t actual;
+    char hw_buf[64] = {};
-    if (eskin_read_register(dev, 0x0000, 4, buf, sizeof(buf), &actual) == ESkinSuccess) {
+    uint32_t hw_len = 0;
-        printf("Serial: %02X %02X %02X %02X\n", buf[0], buf[1], buf[2], buf[3]);
+    eskin_read_hdw_version(dev, hw_buf, sizeof(hw_buf), &hw_len);
+    printf("Hardware version: %.*s\n", (int)hw_len, hw_buf);
+
+    // Streaming 模式：持续采集力数据
+    eskin_start_stream(dev);
+
+    CFingerSample sample;
+    memset(&sample, 0, sizeof(sample));
+    if (eskin_read_sample(dev, 200, &sample) == ESkinSuccess) {
+        printf("force: fx=%u fy=%u fz=%u\n",
+               sample.combined_force.force.fx,
+               sample.combined_force.force.fy,
+               sample.combined_force.force.fz);
     }
 
+    eskin_stop_stream(dev);
     eskin_close(dev);
     return 0;
 }
@@ -108,26 +144,80 @@ cd example/python
 python3 example.py
 ```
 
-> **注意：** Python 示例默认从当前目录加载 `libeskin_finger_sdk.so`，请确保 `.so` 文件已复制到 `example/python/` 目录下，或修改 `example.py` 中的 `LIB_PATH` 指向正确的路径。
+> **注意：** Python 示例默认从当前目录加载 `libeskin_finger_sdk.so`，请确保 `.so` 文件已复制到 `example/python/` 目录下，或修改 `eskin_ffi.py` 中的 `LIB_PATH` 指向正确的路径。
+
+### Python 代码示例
+
+完整示例见 `example/python/example.py`，包含 Command 模式和 Streaming 模式：
 
 ```python
 from eskin_ffi import EskinDevice
 
-with EskinDevice("libeskin_finger_sdk.so") as dev:
+with EskinDevice() as dev:
     dev.open("/dev/ttyUSB0")
 
-    # 读取硬件版本
+    # Command 模式：读取设备信息
     print(f"Hardware version: {dev.read_hdw_version()}")
-
-    # 读取矩阵尺寸
     print(f"Matrix: {dev.read_matrix_row()} x {dev.read_matrix_col()}")
 
-    # 读寄存器
+    # Streaming 模式：持续采集力数据
-    data = dev.read_register(0x0000, 4)
+    dev.start_stream()
-    print(f"Serial: {data.hex()}")
+    for _ in range(10):
+        sample = dev.read_sample(timeout_ms=200)
+        f = sample.combined_force.force
+        print(f"fx={f.fx}  fy={f.fy}  fz={f.fz}")
+    dev.stop_stream()
+```
 
-    # 写寄存器
+---
-    dev.write_register(0x0030, bytes([0x01, 0x00, 0x00, 0x00]))
+
+## ROS2 示例
+
+ROS2 C++ 示例位于 `example/ros-cpp/`，包含：
+
+- `eskin_publisher.cpp` — 独立线程读取力数据，定时发布到 `/comb_force` topic（`std_msgs/UInt32`）
+- `eskin_subscriber.cpp` — 订阅 `/comb_force` topic 并打印
+- `CMakeLists.txt` / `package.xml` — ROS2 包配置
+
+### 构建
+
+```bash
+cd your_ros2_ws/src
+ln -s /path/to/eskin-finger-sdk/example/ros-cpp eskin_example
+cd .. && colcon build --packages-select eskin_example
+```
+
+### 运行
+
+```bash
+# 终端1：启动 publisher（指定设备路径）
+ros2 run eskin_example eskin_publisher /dev/ttyUSB0
+
+# 终端2：订阅数据
+ros2 run eskin_example eskin_subscriber
+```
+
+---
+
+## 数据类型
+
+```c
+typedef struct {
+    uint32_t fx;  // X 轴力（uint32）
+    uint32_t fy;  // Y 轴力（uint32）
+    uint32_t fz;  // Z 轴力（uint32）
+} CForce3D;
+
+typedef struct {
+    uint32_t module;   // 模块编号
+    CForce3D force;    // 三维力
+} CCombinedForce;
+
+typedef struct {
+    uint64_t timestamp_us;    // 时间戳（微秒）
+    uint32_t sequence;        // 序列号
+    CCombinedForce combined_force;  // 组合力数据
+} CFingerSample;
 ```
 
 ---
@@ -150,6 +240,10 @@ with EskinDevice("libeskin_finger_sdk.so") as dev:
 | `eskin_write_device_config2(handle, enable, return_count)` | 写入设备配置寄存器2 |
 | `eskin_write_matrix_row(handle, row, return_count)` | 写入矩阵行数 |
 | `eskin_write_matrix_col(handle, col, return_count)` | 写入矩阵列数 |
+| `eskin_start_stream(handle)` | 启动流式采集 |
+| `eskin_stop_stream(handle)` | 停止流式采集 |
+| `eskin_read_sample(handle, timeout_ms, out)` | 读取一个采样数据 |
+| `eskin_get_mode(handle, out)` | 查询当前设备模式（0=Command, 1=Streaming） |
 
 ---
 
@@ -209,17 +303,17 @@ cargo test protocol::tests   # 仅协议层
 ## 架构
 
 ```text
-User / C / Python
+User / C / Python / ROS2
-       ↓ FFI
+        ↓ FFI
-  DeviceWrapper (handle)
+   DeviceWrapper (handle)
-       ↓
+        ↓
-  EskinDeviceInner
+   EskinDeviceInner
-       ↓ read_register / write_register
+        ↓ read_register / write_register / start_stream / read_sample
-  EskinProtocolCodec (encode/decode + CRC8)
+   EskinProtocolCodec (encode/decode + CRC8)
-       ↓
+        ↓
-  SerialTransport (write/read bytes)
+   SerialTransport (write/read bytes)
-       ↓
+        ↓
-  Hardware (UART)
+   Hardware (UART)
 ```
 
 详细设计见 `docs/PROGRESS.md` 和 `docs/ARCHITECTURE.md`。

example/cpp/main.cpp

@@ -1,49 +1,171 @@
-#include "../../include/eskin_ffi.h"
+#include <algorithm>
+#include <chrono>
+#include <condition_variable>
 #include <cstdint>
 #include <cstdio>
 #include <cstring>
+#include <mutex>
+#include <queue>
+#include <string>
+#include <thread>
+#include <vector>
 
-int main() {
+#include "../../include/eskin_ffi.h"
-    printf("ESkin SDK version: %u.%u.%u\n",
-        eskin_version().major, eskin_version().minor, eskin_version().patch);
 
-    EskinDeviceHandle dev = eskin_open("/dev/ttyUSB0", nullptr);
+using namespace std::chrono_literals;
-    if (!dev) {
+
-        printf("Failed to open device\n");
+// ── Command 模式：读取设备信息 ─────────────────────────────
-        return 1;
+
+static void demo_command_mode(EskinDeviceHandle device) {
+    printf("=== Command Mode ===\n");
+
+    // 硬件版本
+    char hw_buf[64] = {};
+    uint32_t hw_len = 0;
+    if (eskin_read_hdw_version(device, hw_buf, sizeof(hw_buf), &hw_len) == ESkinSuccess) {
+        printf("Hardware version: %.*s\n", (int)hw_len, hw_buf);
     }
-    printf("Device opened\n");
 
-    uint8_t buf[256];
+    // 矩阵尺寸
+    uint8_t row = 0, col = 0;
+    if (eskin_read_matrix_row(device, &row) == ESkinSuccess &&
+        eskin_read_matrix_col(device, &col) == ESkinSuccess) {
+        printf("Matrix size: %u x %u\n", row, col);
+    }
+
+    // 设备配置
+    uint8_t cfg1 = 0;
+    if (eskin_read_device_config1(device, &cfg1) == ESkinSuccess) {
+        printf("Device config1: 0x%02X\n", cfg1);
+    }
+
+    // 序列号（原始寄存器读取）
+    uint8_t buf[256] = {};
     uint32_t actual = 0;
-    EskinSdkErrorCode err = eskin_read_register(dev, 0x0000, 4, buf, sizeof(buf), &actual);
+    if (eskin_read_register(device, 0x1C00, 168, buf, sizeof(buf), &actual) == ESkinSuccess) {
-    if (err == ESkinSuccess) {
+        printf("Serial number (raw): ");
-        printf("Serial number (%u bytes): ", actual);
-        for (uint32_t i = 0; i < actual; i++) {
-            printf("%02X ", buf[i]);
-        }
-
-        printf("\n");
-    } 
-    else {
-        printf("read_register failed: %d\n", err);
-    }
-
-    err = eskin_read_register(dev, 0x000F, 2, buf, sizeof(buf), &actual);
-    if (err == ESkinSuccess) {
-        printf("Firmware version (%u bytes): ", actual);
         for (uint32_t i = 0; i < actual; i++) {
             printf("%02X", buf[i]);
         }
         printf("\n");
     }
+}
 
-    err = eskin_read_register(dev, 0x0500, 168, buf, sizeof(buf), &actual);
+// ── Streaming 模式：持续采集力数据 ────────────────────────
-    if (err == ESkinSuccess) {
+
-        printf("Combined force raw (%u bytes)\n");
+static void demo_streaming(EskinDeviceHandle device, double duration_sec = 5.0) {
+    printf("\n=== Streaming Mode ===\n");
+
+    auto err = eskin_start_stream(device);
+    if (err != ESkinSuccess) {
+        printf("Failed to start stream, error: %d\n", (int)err);
+        return;
+    }
+    printf("Streaming started, will run for %.1fs ...\n", duration_sec);
+
+    // 线程安全队列（参考 ROS publisher 的 read_loop + publish_callback 分离模式）
+    std::mutex mtx;
+    std::queue<CFingerSample> queue;
+    std::queue<std::vector<uint8_t>> raw_queue;
+    bool running = true;
+
+    // 读取线程：持续从设备读取 sample 和原始帧放入队列
+    std::thread read_thread([&]() {
+        while (running) {
+            CFingerSample sample;
+            memset(&sample, 0, sizeof(sample));
+            auto e = eskin_read_sample(device, 50, &sample);
+            if (e == ESkinSuccess) {
+                uint8_t raw_buf[512] = {};
+                uint32_t raw_len = 0;
+                auto raw_err = eskin_read_stream_frame(
+                    device, 1, raw_buf, sizeof(raw_buf), &raw_len);
+                std::vector<uint8_t> raw_frame;
+                if (raw_err == ESkinSuccess) {
+                    raw_frame.assign(raw_buf, raw_buf + std::min<uint32_t>(raw_len, sizeof(raw_buf)));
+                }
+
+                std::lock_guard<std::mutex> lock(mtx);
+                queue.push(sample);
+                raw_queue.push(std::move(raw_frame));
+                while (queue.size() > 100) {
+                    queue.pop();  // 防止堆积
+                }
+                while (raw_queue.size() > 100) {
+                    raw_queue.pop();
+                }
+            }
+            // 超时等非致命错误忽略，继续读取
+        }
+    });
+
+    // 主线程：从队列取数据并打印（类似 ROS 的 publish_callback）
+    auto start = std::chrono::steady_clock::now();
+    int count = 0;
+
+    while (true) {
+        auto now = std::chrono::steady_clock::now();
+        double elapsed = std::chrono::duration<double>(now - start).count();
+        if (elapsed >= duration_sec) break;
+
+        {
+            std::lock_guard<std::mutex> lock(mtx);
+            while (!queue.empty()) {
+                const auto &s = queue.front();
+                size_t raw_len = 0;
+                if (!raw_queue.empty()) {
+                    raw_len = raw_queue.front().size();
+                    raw_queue.pop();
+                }
+
+                printf("[%5u] module=%u  fx=%u  fy=%u  fz=%u  raw_len=%zu\n",
+                       s.sequence, s.combined_force.module,
+                       s.combined_force.force.fx,
+                       s.combined_force.force.fy,
+                       s.combined_force.force.fz,
+                       raw_len);
+                queue.pop();
+                count++;
+            }
+        }
+
+        std::this_thread::sleep_for(5ms);
     }
 
-    eskin_close(dev);
+    running = false;
+    read_thread.join();
+    eskin_stop_stream(device);
+    printf("Streaming stopped. Total samples: %d\n", count);
+}
+
+// ── Main ──────────────────────────────────────────────────
+
+int main(int argc, char *argv[]) {
+    std::string device_path = "/dev/ttyUSB0";
+    if (argc > 1) {
+        device_path = argv[1];
+    }
+
+    // SDK 版本
+    auto ver = eskin_version();
+    printf("ESkin SDK version: %u.%u.%u\n", ver.major, ver.minor, ver.patch);
+
+    // 打开设备
+    EskinDeviceHandle device = eskin_open(device_path.c_str(), nullptr);
+    if (!device) {
+        fprintf(stderr, "Failed to open device: %s\n", device_path.c_str());
+        return 1;
+    }
+    printf("Device opened: %s\n", device_path.c_str());
+
+    // Command 模式演示
+    demo_command_mode(device);
+
+    // Streaming 模式演示
+    demo_streaming(device, 5.0);
+
+    // 关闭设备
+    eskin_close(device);
     printf("Device closed\n");
     return 0;
-}
+}

example/python/eskin_ffi.py

@@ -1,7 +1,7 @@
 import ctypes
 from ctypes import (
     Structure, POINTER, c_void_p, c_char, c_char_p, c_uint8, c_uint16,
-    c_uint32, c_uint64, c_int16, c_bool
+    c_uint32, c_uint64, c_bool
 )
 
 LIB_PATH = "./libeskin_finger_sdk.so"
@@ -14,6 +14,29 @@ class EskinSdkVersion(Structure):
     ]
 
 
+class CForce3D(Structure):
+    _fields_ = [
+        ("fx", c_uint32),
+        ("fy", c_uint32),
+        ("fz", c_uint32),
+    ]
+
+
+class CCombinedForce(Structure):
+    _fields_ = [
+        ("module", c_uint32),
+        ("force", CForce3D),
+    ]
+
+
+class CFingerSample(Structure):
+    _fields_ = [
+        ("timestamp_us", c_uint64),
+        ("sequence", c_uint32),
+        ("combined_force", CCombinedForce),
+    ]
+
+
 class EskinDevice:
     def __init__(self):
         self._lib = ctypes.CDLL(LIB_PATH)
@@ -90,6 +113,27 @@ class EskinDevice:
             c_void_p, c_uint8, POINTER(c_uint16)
         ]
 
+        # Streaming bindings
+
+        lib.eskin_start_stream.restype = c_uint32
+        lib.eskin_start_stream.argtypes = [c_void_p]
+
+        lib.eskin_stop_stream.restype = c_uint32
+        lib.eskin_stop_stream.argtypes = [c_void_p]
+
+        lib.eskin_read_sample.restype = c_uint32
+        lib.eskin_read_sample.argtypes = [
+            c_void_p, c_uint32, POINTER(CFingerSample)
+        ]
+
+        lib.eskin_read_stream_frame.restype = c_uint32
+        lib.eskin_read_stream_frame.argtypes = [
+            c_void_p, c_uint32, POINTER(c_uint8), c_uint32, POINTER(c_uint32)
+        ]
+
+        lib.eskin_get_mode.restype = c_uint32
+        lib.eskin_get_mode.argtypes = [c_void_p, POINTER(c_uint32)]
+
     def version(self) -> tuple:
         v = self._lib.eskin_version()
         return (v.major, v.minor, v.patch)
@@ -210,6 +254,47 @@ class EskinDevice:
             raise RuntimeError(f"write_matrix_col failed: error={err}")
         return ret.value
 
+    # Streaming methods
+
+    def start_stream(self):
+        """启动流式采集"""
+        err = self._lib.eskin_start_stream(self._handle)
+        if err != 0:
+            raise RuntimeError(f"start_stream failed: error={err}")
+
+    def stop_stream(self):
+        """停止流式采集"""
+        err = self._lib.eskin_stop_stream(self._handle)
+        if err != 0:
+            raise RuntimeError(f"stop_stream failed: error={err}")
+
+    def read_sample(self, timeout_ms: int = 200) -> CFingerSample:
+        """读取一个采样数据（流模式下调用）"""
+        sample = CFingerSample()
+        err = self._lib.eskin_read_sample(self._handle, timeout_ms, ctypes.byref(sample))
+        if err != 0:
+            raise RuntimeError(f"read_sample failed: error={err}")
+        return sample
+
+    def read_stream_frame(self, timeout_ms: int = 200, max_len: int = 512) -> bytes:
+        """读取一个 stream 原始完整协议帧（流模式下调用）"""
+        buf = (c_uint8 * max_len)()
+        actual = c_uint32(0)
+        err = self._lib.eskin_read_stream_frame(
+            self._handle, timeout_ms, buf, len(buf), ctypes.byref(actual)
+        )
+        if err != 0:
+            raise RuntimeError(f"read_stream_frame failed: error={err}")
+        return bytes(buf[:min(actual.value, len(buf))])
+
+    def get_mode(self) -> int:
+        """查询当前设备模式（0=Command, 1=Streaming）"""
+        out = c_uint32(0)
+        err = self._lib.eskin_get_mode(self._handle, ctypes.byref(out))
+        if err != 0:
+            raise RuntimeError(f"get_mode failed: error={err}")
+        return out.value
+
     def __enter__(self):
         return self
 

example/python/example.py

@@ -1,51 +1,97 @@
-from eskin_ffi import EskinDevice
+import time
+import threading
+from collections import deque
+
+from eskin_ffi import EskinDevice, CFingerSample
+
+
+def demo_command_mode(dev: EskinDevice):
+    """Command 模式：读取设备信息、寄存器等"""
+    print("=== Command Mode ===")
+
+    hdw_ver = dev.read_hdw_version()
+    print(f"Hardware version: {hdw_ver}")
+
+    row = dev.read_matrix_row()
+    col = dev.read_matrix_col()
+    print(f"Matrix size: {row} x {col}")
+
+    cfg1 = dev.read_device_config1()
+    print(f"Device config1: 0x{cfg1:02X}")
+
+    data = dev.read_register(0x1C00, 168)
+    print(f"Serial number: {data.hex().upper()}")
+
+
+def demo_streaming(dev: EskinDevice, duration_sec: float = 5.0):
+    """Streaming 模式：持续采集力数据（参考 ROS C++ publisher）"""
+    print("\n=== Streaming Mode ===")
+
+    # 启动流式采集
+    dev.start_stream()
+    print(f"Streaming started, will run for {duration_sec}s ...")
+
+    # 线程安全的队列（参考 ROS demo 的 read_loop + publish_callback 分离模式）
+    queue: deque = deque(maxlen=100)
+    raw_queue: deque = deque(maxlen=100)
+    running = True
+
+    def read_loop():
+        """独立读取线程：持续从设备读取 sample 和原始帧"""
+        while running:
+            try:
+                sample = dev.read_sample(timeout_ms=50)
+                queue.append(sample)
+                raw_frame = dev.read_stream_frame(timeout_ms=1)
+                raw_queue.append(raw_frame)
+            except RuntimeError:
+                # 超时等非致命错误，继续读取
+                pass
+
+    # 启动读取线程
+    reader = threading.Thread(target=read_loop, daemon=True)
+    reader.start()
+
+    # 主线程：从队列取数据并打印（类似 ROS 的 publish_callback）
+    start = time.monotonic()
+    count = 0
+    while time.monotonic() - start < duration_sec:
+        if queue:
+            sample: CFingerSample = queue.popleft()
+            raw_frame = raw_queue.popleft() if raw_queue else b""
+            f = sample.combined_force.force
+            mod = sample.combined_force.module
+            print(
+                f"[{sample.sequence:5d}] "
+                f"module={mod}  "
+                f"fx={f.fx}  fy={f.fy}  fz={f.fz}  "
+                f"raw_len={len(raw_frame)}"
+            )
+            count += 1
+        else:
+            time.sleep(0.005)
+
+    running = False
+    reader.join(timeout=1.0)
+    dev.stop_stream()
+    print(f"Streaming stopped. Total samples: {count}")
+
 
 def main():
-    dev = EskinDevice()
+    ver = EskinDevice().version()
-
-    # SDK 版本
-    ver = dev.version()
     print(f"ESkin SDK version: {ver[0]}.{ver[1]}.{ver[2]}")
 
-    # 打开设备
+    device_path = "/dev/ttyUSB0"
-    dev.open("/dev/ttyUSB0")
-    print("Device opened")
 
-    try:
+    with EskinDevice() as dev:
-        # 读取硬件版本
+        dev.open(device_path)
-        hdw_ver = dev.read_hdw_version()
+        print(f"Device opened: {device_path}")
-        print(f"Hardware version: {hdw_ver}")
 
-        # 读取矩阵尺寸
+        demo_command_mode(dev)
-        row = dev.read_matrix_row()
+        demo_streaming(dev, duration_sec=5.0)
-        col = dev.read_matrix_col()
-        print(f"Matrix size: {row} x {col}")
 
-        # 读取设备配置
+    print("Device closed")
-        cfg1 = dev.read_device_config1()
-        # cfg2 = dev.read_device_config2()
-        print(f"Device config1: 0x{cfg1:02X}")
-        # print(f"Device config2: 0x{cfg2:02X}")
 
-        # 写入矩阵尺寸示例
-        # ret = dev.write_matrix_row(16)
-        # print(f"Write matrix row: returned {ret} bytes")
-        # ret = dev.write_matrix_col(16)
-        # print(f"Write matrix col: returned {ret} bytes")
-
-        # 写入设备配置示例
-        # ret = dev.write_device_config1(True)
-        # print(f"Write device config1: returned {ret} bytes")
-        # ret = dev.write_device_config2(False)
-        # print(f"Write device config2: returned {ret} bytes")
-
-        # 原始寄存器读写
-        data = dev.read_register(0x1C00, 168)
-        print(f"Serial number: {data.hex().upper()}")
-
-    finally:
-        dev.close()
-        print("Device closed")
 
 if __name__ == "__main__":
-    main()
+    main()

example/ros-cpp/CMakeLists.txt

@@ -0,0 +1,52 @@
+cmake_minimum_required(VERSION 3.8)
+project(eskin_ros2_demo)
+
+if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+  add_compile_options(-Wall -Wextra -Wpedantic)
+endif()
+
+# Force use of system Python (avoid Conda Python interfering with ROS 2)
+set(Python3_EXECUTABLE /usr/bin/python3 CACHE FILEPATH "System Python3" FORCE)
+
+# Ensure ROS 2 Python packages are findable even without ROS 2 sourced (e.g. VS Code CMake Tools)
+set(ENV{PYTHONPATH} "/opt/ros/jazzy/lib/python3.12/site-packages:$ENV{PYTHONPATH}")
+
+# find dependencies
+find_package(ament_cmake REQUIRED)
+find_package(rclcpp REQUIRED)
+find_package(std_msgs REQUIRED)
+
+
+if(BUILD_TESTING)
+  find_package(ament_lint_auto REQUIRED)
+  # the following line skips the linter which checks for copyrights
+  # comment the line when a copyright and license is added to all source files
+  set(ament_cmake_copyright_FOUND TRUE)
+  # the following line skips cpplint (only works in a git repo)
+  # comment the line when this package is in a git repo and when
+  # a copyright and license is added to all source files
+  set(ament_cmake_cpplint_FOUND TRUE)
+  ament_lint_auto_find_test_dependencies()
+endif()
+
+# Eskin SDK library
+set(ESKIN_SDK_DIR "/home/lenn/Workspace/eskin-finger-sdk" CACHE PATH "Path to eskin-finger-sdk")
+add_library(eskin_finger_sdk SHARED IMPORTED)
+set_target_properties(eskin_finger_sdk PROPERTIES
+  IMPORTED_LOCATION "${ESKIN_SDK_DIR}/target/release/libeskin_finger_sdk.so"
+  INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_SOURCE_DIR}/include"
+)
+
+add_executable(eskin_publisher src/eskin_publisher.cpp)
+ament_target_dependencies(eskin_publisher rclcpp std_msgs)
+target_link_libraries(eskin_publisher eskin_finger_sdk pthread)
+
+add_executable(eskin_subscriber src/eskin_subscriber.cpp)
+ament_target_dependencies(eskin_subscriber rclcpp std_msgs)
+
+install(TARGETS
+  eskin_publisher
+  eskin_subscriber
+  DESTINATION lib/${PROJECT_NAME}
+)
+ament_package()

example/ros-cpp/eskin_publisher.cpp

@@ -0,0 +1,130 @@
+#include <chrono>
+#include <condition_variable>
+#include <cstdint>
+#include <cstdio>
+#include <cstring>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <queue>
+#include <string>
+#include <thread>
+
+#include "rclcpp/rclcpp.hpp"
+#include "std_msgs/msg/u_int32.hpp"
+
+#include "../include/eskin_ffi.h"
+
+using namespace std::chrono_literals;
+
+class EskinPublisher : public rclcpp::Node {
+public:
+  EskinPublisher(const std::string & device_path)
+  : Node("eskin_publisher"), running_(true)
+  {
+    // 打开设备
+    device_ = eskin_open(device_path.c_str(), nullptr);
+    if (!device_) {
+      RCLCPP_FATAL(this->get_logger(), "Failed to open device: %s", device_path.c_str());
+      rclcpp::shutdown();
+      return;
+    }
+    RCLCPP_INFO(this->get_logger(), "Device opened: %s", device_path.c_str());
+
+    // 启动 streaming
+    auto err = eskin_start_stream(device_);
+    if (err != ESkinSuccess) {
+      RCLCPP_FATAL(this->get_logger(), "Failed to start stream, error: %d", (int)err);
+      eskin_close(device_);
+      rclcpp::shutdown();
+      return;
+    }
+    RCLCPP_INFO(this->get_logger(), "Streaming started");
+
+    // 创建 publisher
+    publisher_ = this->create_publisher<std_msgs::msg::UInt32>("comb_force", 10);
+
+    // 启动独立读取线程
+    read_thread_ = std::thread(&EskinPublisher::read_loop, this);
+
+    // 10ms 定时器：从队列取数据并发布
+    timer_ = this->create_wall_timer(10ms, std::bind(&EskinPublisher::publish_callback, this));
+
+    RCLCPP_INFO(this->get_logger(), "EskinPublisher setup success");
+  }
+
+  ~EskinPublisher() {
+    // 停止读取线程
+    running_ = false;
+    cv_.notify_all();
+    if (read_thread_.joinable()) {
+      read_thread_.join();
+    }
+
+    // 停止 streaming 并关闭设备
+    if (device_) {
+      eskin_stop_stream(device_);
+      eskin_close(device_);
+    }
+    RCLCPP_INFO(this->get_logger(), "EskinPublisher destroyed");
+  }
+
+private:
+  // 独立读取线程：持续从设备读取 sample 放入队列
+  void read_loop() {
+    while (running_) {
+      CFingerSample sample;
+      memset(&sample, 0, sizeof(sample));
+      EskinSdkErrorCode err = eskin_read_sample(device_, 50, &sample);
+      if (err == ESkinSuccess) {
+        std::lock_guard<std::mutex> lock(queue_mutex_);
+        sample_queue_.push(sample);
+        // 限制队列大小，防止堆积
+        while (sample_queue_.size() > 100) {
+          sample_queue_.pop();
+        }
+      } else if (err != ESkinTimeout) {
+        RCLCPP_WARN_THROTTLE(this->get_logger(), *this->get_clock(), 1000,
+          "eskin_read_sample error: %d", (int)err);
+      }
+    }
+  }
+
+  // 定时器回调：从队列取数据并发布到 ROS topic
+  void publish_callback() {
+    std::lock_guard<std::mutex> lock(queue_mutex_);
+    while (!sample_queue_.empty()) {
+      const auto & sample = sample_queue_.front();
+      auto msg = std_msgs::msg::UInt32();
+      // 使用 combined_force 中的 fz（法向力）作为发布值
+      msg.data = static_cast<uint32_t>(sample.combined_force.force.fz);
+      publisher_->publish(msg);
+      sample_queue_.pop();
+    }
+  }
+
+  bool running_;
+  EskinDeviceHandle device_;
+  std::thread read_thread_;
+  std::mutex queue_mutex_;
+  std::queue<CFingerSample> sample_queue_;
+  std::condition_variable cv_;
+
+  rclcpp::TimerBase::SharedPtr timer_;
+  rclcpp::Publisher<std_msgs::msg::UInt32>::SharedPtr publisher_;
+};
+
+int main(int argc, char * argv[]) {
+  rclcpp::init(argc, argv);
+
+  // 设备路径可通过命令行参数传入，默认 /dev/ttyUSB0
+  std::string device_path = "/dev/ttyUSB0";
+  if (argc > 1) {
+    device_path = argv[1];
+  }
+
+  auto node = std::make_shared<EskinPublisher>(device_path);
+  rclcpp::spin(node);
+  rclcpp::shutdown();
+  return 0;
+}

example/ros-cpp/eskin_subscriber.cpp

@@ -0,0 +1,32 @@
+#include <memory>
+
+#include "rclcpp/rclcpp.hpp"
+#include "std_msgs/msg/u_int32.hpp"
+
+using std::placeholders::_1;
+
+class EskinSubscriber : public rclcpp::Node {
+public:
+  EskinSubscriber()
+  : Node("eskin_subscriber")
+  {
+    subscription_ = this->create_subscription<std_msgs::msg::UInt32>(
+      "comb_force", 10,
+      std::bind(&EskinSubscriber::topic_callback, this, _1));
+    RCLCPP_INFO(this->get_logger(), "EskinSubscriber listening on /comb_force");
+  }
+
+private:
+  void topic_callback(const std_msgs::msg::UInt32::SharedPtr msg) const {
+    RCLCPP_INFO(this->get_logger(), "Received force: %u", msg->data);
+  }
+
+  rclcpp::Subscription<std_msgs::msg::UInt32>::SharedPtr subscription_;
+};
+
+int main(int argc, char * argv[]) {
+  rclcpp::init(argc, argv);
+  rclcpp::spin(std::make_shared<EskinSubscriber>());
+  rclcpp::shutdown();
+  return 0;
+}

example/ros-cpp/package.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0"?>
+<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
+<package format="3">
+  <name>eskin_ros2_demo</name>
+  <version>0.0.0</version>
+  <description>TODO: Package description</description>
+  <maintainer email="lenn@todo.todo">lenn</maintainer>
+  <license>TODO: License declaration</license>
+
+  <buildtool_depend>ament_cmake</buildtool_depend>
+
+  <depend>rclcpp</depend>
+  <depend>std_msgs</depend>
+
+  <test_depend>ament_lint_auto</test_depend>
+  <test_depend>ament_lint_common</test_depend>
+
+  <export>
+    <build_type>ament_cmake</build_type>
+  </export>
+</package>

include/eskin_ffi.h

@@ -113,8 +113,39 @@ EskinSdkErrorCode eskin_write_matrix_col(
     uint16_t* return_count
 );
 
+// Streaming interfaces
+
+typedef struct {
+    uint32_t fx;
+    uint32_t fy;
+    uint32_t fz;
+} CForce3D;
+
+typedef struct {
+    uint32_t module;
+    CForce3D force;
+} CCombinedForce;
+
+typedef struct {
+    uint64_t timestamp_us;
+    uint32_t sequence;
+    CCombinedForce combined_force;
+} CFingerSample;
+
+EskinSdkErrorCode eskin_start_stream(EskinDeviceHandle handle);
+EskinSdkErrorCode eskin_stop_stream(EskinDeviceHandle handle);
+EskinSdkErrorCode eskin_read_sample(EskinDeviceHandle handle, uint32_t timeout_ms, CFingerSample* out);
+EskinSdkErrorCode eskin_read_stream_frame(
+    EskinDeviceHandle handle,
+    uint32_t timeout_ms,
+    uint8_t* buf,
+    uint32_t buf_len,
+    uint32_t* actual_len
+);
+EskinSdkErrorCode eskin_get_mode(EskinDeviceHandle handle, uint32_t* out);
+
 #ifdef __cplusplus
 }
 #endif
 
-#endif
+#endif

src/channel.rs

@@ -37,6 +37,9 @@ pub struct ChannelManager {
     pub sample_tx: Sender<FingerSample>,
     pub sample_rx: Receiver<FingerSample>,
 
+    pub raw_frame_tx: Sender<Vec<u8>>,
+    pub raw_frame_rx: Receiver<Vec<u8>>,
+
     pub cmd_tx: Sender<DeviceCommand>,
     pub cmd_rx: Receiver<DeviceCommand>,
 
@@ -56,12 +59,15 @@ impl ChannelManager {
         drop_policy: DropPolicy,
     ) -> Self {
         let (sample_tx, sample_rx) = bounded(sample_capacity);
+        let (raw_frame_tx, raw_frame_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,
+            raw_frame_tx,
+            raw_frame_rx,
             cmd_tx,
             cmd_rx,
             event_tx,
@@ -111,6 +117,46 @@ impl ChannelManager {
             })
     }
 
+    pub fn send_raw_frame(&self, frame: Vec<u8>) -> Result<(), SdkError> {
+        match self.drop_policy {
+            DropPolicy::DropNewest => match self.raw_frame_tx.try_send(frame) {
+                Ok(()) => Ok(()),
+                Err(TrySendError::Full(_)) => {
+                    self.record_sample_drop();
+                    Ok(())
+                }
+                Err(TrySendError::Disconnected(_)) => Err(SdkError::ChannelClosed),
+            },
+            DropPolicy::DropOldest => match self.raw_frame_tx.try_send(frame) {
+                Ok(()) => Ok(()),
+                Err(TrySendError::Full(frame)) => {
+                    let _ = self.raw_frame_rx.try_recv();
+                    self.record_sample_drop();
+
+                    match self.raw_frame_tx.try_send(frame) {
+                        Ok(()) => Ok(()),
+                        Err(TrySendError::Full(_)) => {
+                            self.record_sample_drop();
+                            Ok(())
+                        }
+                        Err(TrySendError::Disconnected(_)) => Err(SdkError::ChannelClosed),
+                    }
+                }
+                Err(TrySendError::Disconnected(_)) => Err(SdkError::ChannelClosed),
+            },
+        }
+    }
+
+    pub fn recv_raw_frame(&self, timeout_ms: u32) -> Result<Vec<u8>, SdkError> {
+        let timeout = std::time::Duration::from_millis(timeout_ms as u64);
+        self.raw_frame_rx
+            .recv_timeout(timeout)
+            .map_err(|err| match err {
+                RecvTimeoutError::Timeout => SdkError::Timeout,
+                RecvTimeoutError::Disconnected => SdkError::ChannelClosed,
+            })
+    }
+
     pub fn send_cmd(&self, cmd: DeviceCommand) -> Result<(), SdkError> {
         self.cmd_tx.try_send(cmd).map_err(|err| match err {
             TrySendError::Full(_) => SdkError::BufferOverflow(1),

src/device.rs

@@ -6,10 +6,9 @@ use crate::{
     config::{DeviceConfig, DeviceInfo},
     error::SdkError,
     protocol::{
-        EskinProtocolCodec, FRAME_START_RESPONSE, ProtocolCodec,
+        EskinProtocolCodec, FRAME_START_RESPONSE, ProtocolCodec, ReadRequest, WriteRequest,
-        ReadRequest, WriteRequest,
     },
-    stream::StreamRuntime,
+    stream::{StreamConfig, StreamController, StreamRuntime},
     transport::{SerialTransport, SharedSerialTransport},
     types::FingerSample,
 };
@@ -18,17 +17,24 @@ use crate::{
 pub enum DeviceState {
     Closed,
     Open,
-    Streaming,
     Error,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DeviceMode {
+    Command,
+    Streaming,
+}
+
 pub struct EskinDeviceInner {
     pub info: DeviceInfo,
     pub config: DeviceConfig,
     pub channels: Arc<ChannelManager>,
     pub state: DeviceState,
+    pub mode: DeviceMode,
     pub transport: SharedSerialTransport,
     pub codec: Box<dyn ProtocolCodec>,
+    stream: Option<StreamRuntime>,
 }
 
 impl EskinDeviceInner {
@@ -45,8 +51,10 @@ impl EskinDeviceInner {
             config,
             channels: Arc::new(channels),
             state: DeviceState::Closed,
+            mode: DeviceMode::Command,
             transport: Arc::new(Mutex::new(transport)),
             codec: Box::new(EskinProtocolCodec),
+            stream: None,
         }
     }
 
@@ -63,8 +71,10 @@ impl EskinDeviceInner {
             config,
             channels: Arc::new(channels),
             state: DeviceState::Closed,
+            mode: DeviceMode::Command,
             transport,
             codec: Box::new(EskinProtocolCodec),
+            stream: None,
         }
     }
 
@@ -83,9 +93,18 @@ impl EskinDeviceInner {
             let remaining = deadline
                 .checked_duration_since(std::time::Instant::now())
                 .unwrap_or(std::time::Duration::from_millis(1));
-            debug_println!("[device] read_exact: need {} bytes, have {} so far, remaining timeout: {:?}", buf.len() - offset, offset, remaining);
+            debug_println!(
+                "[device] read_exact: need {} bytes, have {} so far, remaining timeout: {:?}",
+                buf.len() - offset,
+                offset,
+                remaining
+            );
             let n = transport.read(&mut buf[offset..], Duration::from_std(remaining).unwrap())?;
-            debug_println!("[device] read_exact: got {} bytes: {:02X?}", n, &buf[offset..offset + n]);
+            debug_println!(
+                "[device] read_exact: got {} bytes: {:02X?}",
+                n,
+                &buf[offset..offset + n]
+            );
 
             if n == 0 {
                 return Err(SdkError::Timeout);
@@ -135,12 +154,19 @@ impl EskinDeviceInner {
 
     fn ensure_open(&self) -> Result<(), SdkError> {
         match self.state {
-            DeviceState::Open | DeviceState::Streaming => Ok(()),
+            DeviceState::Open => Ok(()),
             DeviceState::Closed => Err(SdkError::NotInitialized),
             DeviceState::Error => Err(SdkError::InternalError("device is in error state".into())),
         }
     }
 
+    fn ensure_command_mode(&self) -> Result<(), SdkError> {
+        match self.mode {
+            DeviceMode::Command => Ok(()),
+            DeviceMode::Streaming => Err(SdkError::StreamingBusy),
+        }
+    }
+
     pub fn channels(&self) -> Arc<ChannelManager> {
         Arc::clone(&self.channels)
     }
@@ -152,8 +178,6 @@ impl EskinDeviceInner {
     pub fn shared_transport(&self) -> SharedSerialTransport {
         Arc::clone(&self.transport)
     }
-
-
 }
 
 pub trait EskinDeviceFunc {
@@ -165,12 +189,13 @@ pub trait EskinDeviceFunc {
     fn write_device_config1(&mut self, enable: bool) -> Result<u16, SdkError>;
     fn write_device_config2(&mut self, enable: bool) -> Result<u16, SdkError>;
     fn write_matrix_row(&mut self, row: u8) -> Result<u16, SdkError>;
-    fn write_matrix_col(&mut self, col: u8) -> Result<u16, SdkError>; 
+    fn write_matrix_col(&mut self, col: u8) -> Result<u16, SdkError>;
 }
 
 impl EskinDeviceFunc for EskinDeviceInner {
     fn read_hdw_version(&mut self) -> Result<String, SdkError> {
-        let hdw = self.read_register(0, 2)
+        let hdw = self
+            .read_register(0, 2)
             .map_err(|_| SdkError::FrameError("read hardware version failed".into()))?;
 
         let version = format!("{}.{}", hdw[0], hdw[1]);
@@ -178,39 +203,45 @@ impl EskinDeviceFunc for EskinDeviceInner {
     }
 
     fn read_matrix_row(&mut self) -> Result<u8, SdkError> {
-        let row = self.read_register(0x0015, 1)
+        let row = self
+            .read_register(0x0015, 1)
             .map_err(|_| SdkError::FrameError("read matrix row failed".into()))?;
 
         Ok(row[0])
     }
 
     fn read_matrix_col(&mut self) -> Result<u8, SdkError> {
-        let col = self.read_register(0x0014, 1)
+        let col = self
+            .read_register(0x0014, 1)
             .map_err(|_| SdkError::FrameError("read matrix col failed".into()))?;
 
         Ok(col[0])
     }
 
     fn write_matrix_row(&mut self, row: u8) -> Result<u16, SdkError> {
-        let res = self.write_register(0x0015, &[row])
+        let res = self
+            .write_register(0x0015, &[row])
             .map_err(|_| SdkError::FrameError("write matrix row failed".into()))?;
         Ok(res)
     }
 
     fn write_matrix_col(&mut self, col: u8) -> Result<u16, SdkError> {
-        let res = self.write_register(0x0015, &[col])
+        let res = self
+            .write_register(0x0015, &[col])
             .map_err(|_| SdkError::FrameError("write matrix row failed".into()))?;
         Ok(res)
     }
 
     fn read_device_config1(&mut self) -> Result<u8, SdkError> {
-        let enabled = self.read_register(0x0017, 1)
+        let enabled = self
+            .read_register(0x0017, 1)
             .map_err(|_| SdkError::FrameError("read device config1 failed".into()))?;
         Ok(enabled[0])
     }
 
     fn read_device_config2(&mut self) -> Result<u8, SdkError> {
-        let enabled = self.read_register(0x0018, 1)
+        let enabled = self
+            .read_register(0x0018, 1)
             .map_err(|_| SdkError::FrameError("read device config2 failed".into()))?;
         Ok(enabled[0])
     }
@@ -230,12 +261,14 @@ pub trait EskinDevice {
     fn open(&mut self) -> Result<(), SdkError>;
     fn close(&mut self) -> Result<(), SdkError>;
     fn state(&self) -> DeviceState;
+    fn mode(&self) -> DeviceMode;
     fn device_info(&self) -> Result<DeviceInfo, SdkError>;
     fn config(&self) -> &DeviceConfig;
     fn apply_config(&mut self, config: DeviceConfig) -> Result<(), SdkError>;
     fn start_stream(&mut self) -> Result<(), SdkError>;
     fn stop_stream(&mut self) -> Result<(), SdkError>;
     fn read_sample(&self, timeout_ms: u32) -> Result<FingerSample, SdkError>;
+    fn read_stream_frame(&self, timeout_ms: u32) -> Result<Vec<u8>, SdkError>;
     fn read_event(&self, timeout_ms: u32) -> Result<DeviceEvent, SdkError>;
     fn read_register(&mut self, addr: u32, length: u16) -> Result<Vec<u8>, SdkError>;
     fn write_register(&mut self, addr: u32, data: &[u8]) -> Result<u16, SdkError>;
@@ -253,6 +286,9 @@ impl EskinDevice for EskinDeviceInner {
     }
 
     fn close(&mut self) -> Result<(), SdkError> {
+        if self.mode == DeviceMode::Streaming {
+            self.stop_stream()?;
+        }
         {
             let mut transport = self.lock_transport()?;
             transport.close()?;
@@ -265,6 +301,10 @@ impl EskinDevice for EskinDeviceInner {
         self.state
     }
 
+    fn mode(&self) -> DeviceMode {
+        self.mode
+    }
+
     fn device_info(&self) -> Result<DeviceInfo, SdkError> {
         Ok(self.info.clone())
     }
@@ -279,26 +319,42 @@ impl EskinDevice for EskinDeviceInner {
     }
 
     fn start_stream(&mut self) -> Result<(), SdkError> {
-        if self.state == DeviceState::Streaming {
+        self.ensure_open()?;
-            return Err(SdkError::AlreadyStreaming);
+
+        if self.mode == DeviceMode::Streaming {
+            return Err(SdkError::StreamingBusy);
         }
 
-        if self.state != DeviceState::Open {
+        let stream_config = StreamConfig {
-            return Err(SdkError::NotInitialized);
+            mode: crate::stream::StreamMode::Polling,
-        }
+            device_addr: self.config.device_addr,
+            read_timeout_ms: self.config.read_timeout_ms,
+            ..Default::default()
+        };
+        println!("stream_config: {:?}", stream_config);
+        let mut runtime = self.create_stream_runtime();
+        runtime.start(stream_config)?;
+
+        self.stream = Some(runtime);
+        self.mode = DeviceMode::Streaming;
 
-        self.state = DeviceState::Streaming;
-        self.channels.send_event(DeviceEvent::StreamStarted)?;
         Ok(())
     }
 
     fn stop_stream(&mut self) -> Result<(), SdkError> {
-        if self.state != DeviceState::Streaming {
+        if self.mode != DeviceMode::Streaming {
             return Err(SdkError::NotStreaming);
         }
 
-        self.state = DeviceState::Open;
+        if let Some(mut runtime) = self.stream.take() {
-        self.channels.send_event(DeviceEvent::StreamStopped)?;
+            // Worker 可能已经因为 I/O 错误自行停止，忽略 NotStreaming
+            match runtime.stop() {
+                Ok(()) | Err(SdkError::NotStreaming) => {}
+                Err(e) => return Err(e),
+            }
+        }
+
+        self.mode = DeviceMode::Command;
         Ok(())
     }
 
@@ -306,13 +362,17 @@ impl EskinDevice for EskinDeviceInner {
         self.channels.recv_sample(timeout_ms)
     }
 
+    fn read_stream_frame(&self, timeout_ms: u32) -> Result<Vec<u8>, SdkError> {
+        self.channels.recv_raw_frame(timeout_ms)
+    }
+
     fn read_event(&self, timeout_ms: u32) -> Result<DeviceEvent, SdkError> {
         self.channels.recv_event(timeout_ms)
     }
 
     fn read_register(&mut self, addr: u32, length: u16) -> Result<Vec<u8>, SdkError> {
         self.ensure_open()?;
-
+        self.ensure_command_mode()?;
         let request = ReadRequest {
             device_addr: self.config.device_addr,
             start_addr: addr,
@@ -334,7 +394,7 @@ impl EskinDevice for EskinDeviceInner {
 
     fn write_register(&mut self, addr: u32, data: &[u8]) -> Result<u16, SdkError> {
         self.ensure_open()?;
-
+        self.ensure_command_mode()?;
         let request = WriteRequest {
             device_addr: self.config.device_addr,
             start_addr: addr,

src/error.rs

@@ -18,6 +18,7 @@ pub enum SdkErrorCode {
     FrameError = 15,
     ProtocolError = 16,
     DeviceError = 17,
+    StreamingBusy = 18,
 }
 
 #[derive(Debug, thiserror::Error)]
@@ -69,4 +70,7 @@ pub enum SdkError {
 
     #[error("Device error: status 0x{0:04X}")]
     DeviceError(u16),
+
+    #[error("Device is in streaming mode, command not allowed")]
+    StreamingBusy,
 }

src/ffi/mod.rs

@@ -1,9 +1,9 @@
-use std::{ptr};
+use crate::device::{DeviceMode, EskinDevice, EskinDeviceFunc};
-use std::ffi::{CStr, c_char};
-use crate::device::EskinDevice;
-use crate::device::EskinDeviceFunc;
 use crate::transport::SerialPortTransport;
+use crate::types::{CombinedForce, FingerSample};
 use crate::{config::DeviceConfig, device::EskinDeviceInner, error::SdkErrorCode};
+use std::ffi::{CStr, c_char};
+use std::ptr;
 
 pub type EskinDeviceHandle = *mut core::ffi::c_void;
 
@@ -16,20 +16,31 @@ pub struct EskinSdkVersion {
 }
 
 #[repr(C)]
+#[derive(Debug, Clone, Copy)]
+pub struct CForce3D {
+    pub fx: u32,
+    pub fy: u32,
+    pub fz: u32,
+}
+
+#[repr(C)]
+#[derive(Debug, Clone, Copy)]
+pub struct CCombinedForce {
+    pub module: u32,
+    pub force: CForce3D,
+}
+
+#[repr(C)]
+#[derive(Debug, Clone, Copy)]
 pub struct CFingerSample {
     pub timestamp_us: u64,
     pub sequence: u32,
-    pub combinded_force_raw: *const u8,
+    pub combined_force: CCombinedForce,
-    pub combinded_force_len: u32,
-    pub module_error_raw: *const u8,
-    pub module_error_len: u32,
 }
 
 #[allow(dead_code)]
 struct DeviceWrapper {
     device: EskinDeviceInner,
-    last_cf_raw: Vec<u8>,
-    last_me_raw: Vec<u8>
 }
 
 fn sdk_error_to_code(err: crate::error::SdkError) -> SdkErrorCode {
@@ -50,15 +61,19 @@ fn sdk_error_to_code(err: crate::error::SdkError) -> SdkErrorCode {
         crate::error::SdkError::BufferOverflow(_) => SdkErrorCode::BufferOverflow,
         crate::error::SdkError::InvalidParameter(_) => SdkErrorCode::InvalidParameter,
         crate::error::SdkError::ProtocolError(_) => SdkErrorCode::ProtocolError,
+        crate::error::SdkError::StreamingBusy => SdkErrorCode::StreamingBusy,
     }
 }
 
 #[unsafe(no_mangle)]
 pub extern "C" fn eskin_version() -> EskinSdkVersion {
-    EskinSdkVersion { major: 0, minor: 1, patch: 0 }
+    EskinSdkVersion {
+        major: 0,
+        minor: 1,
+        patch: 0,
+    }
 }
 
-
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn eskin_open(
     path: *const c_char,
@@ -68,11 +83,9 @@ pub unsafe extern "C" fn eskin_open(
         return ptr::null_mut();
     }
 
-    let path_str = match unsafe {
+    let path_str = match unsafe { CStr::from_ptr(path) }.to_str() {
-        CStr::from_ptr(path)
-    }.to_str() {
         Ok(s) => s.to_string(),
-        Err(_) => return ptr::null_mut()
+        Err(_) => return ptr::null_mut(),
     };
 
     let device_config = if config.is_null() {
@@ -83,17 +96,13 @@ pub unsafe extern "C" fn eskin_open(
 
     let transport = SerialPortTransport::new(path_str, 921600);
     let mut device = EskinDeviceInner::new(device_config, Box::new(transport));
-    
+
     if device.open().is_err() {
         return ptr::null_mut();
     }
 
-    let wrapper = Box::new(DeviceWrapper {
+    let wrapper = Box::new(DeviceWrapper { device });
-        device,
+
-        last_cf_raw: Vec::new(),
-        last_me_raw: Vec::new(),
-    });
-    
     Box::into_raw(wrapper) as EskinDeviceHandle
 }
 
@@ -370,3 +379,121 @@ pub unsafe extern "C" fn eskin_write_matrix_col(
         Err(e) => sdk_error_to_code(e),
     }
 }
+
+/// 启动流式采集
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn eskin_start_stream(handle: EskinDeviceHandle) -> SdkErrorCode {
+    if handle.is_null() {
+        return SdkErrorCode::InvalidPointer;
+    }
+
+    let wrapper = unsafe { &mut *(handle as *mut DeviceWrapper) };
+
+    match wrapper.device.start_stream() {
+        Ok(()) => SdkErrorCode::Success,
+        Err(e) => sdk_error_to_code(e),
+    }
+}
+
+/// 停止流式采集
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn eskin_stop_stream(handle: EskinDeviceHandle) -> SdkErrorCode {
+    if handle.is_null() {
+        return SdkErrorCode::InvalidPointer;
+    }
+
+    let wrapper = unsafe { &mut *(handle as *mut DeviceWrapper) };
+
+    match wrapper.device.stop_stream() {
+        Ok(()) => SdkErrorCode::Success,
+        Err(e) => sdk_error_to_code(e),
+    }
+}
+
+/// 读取一个采样数据（流模式下调用）
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn eskin_read_sample(
+    handle: EskinDeviceHandle,
+    timeout_ms: u32,
+    out: *mut CFingerSample,
+) -> SdkErrorCode {
+    if handle.is_null() || out.is_null() {
+        return SdkErrorCode::InvalidPointer;
+    }
+
+    let wrapper = unsafe { &mut *(handle as *mut DeviceWrapper) };
+
+    match wrapper.device.read_sample(timeout_ms) {
+        Ok(sample) => {
+            let c_sample = finger_sample_to_c(&sample);
+            unsafe { *out = c_sample };
+            SdkErrorCode::Success
+        }
+        Err(e) => sdk_error_to_code(e),
+    }
+}
+
+/// 读取一个 stream 原始完整协议帧（流模式下调用）
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn eskin_read_stream_frame(
+    handle: EskinDeviceHandle,
+    timeout_ms: u32,
+    buf: *mut u8,
+    buf_len: u32,
+    actual_len: *mut u32,
+) -> SdkErrorCode {
+    if handle.is_null() || buf.is_null() || actual_len.is_null() {
+        return SdkErrorCode::InvalidPointer;
+    }
+
+    let wrapper = unsafe { &mut *(handle as *mut DeviceWrapper) };
+
+    let frame = match wrapper.device.read_stream_frame(timeout_ms) {
+        Ok(frame) => frame,
+        Err(e) => return sdk_error_to_code(e),
+    };
+
+    let copy_len = std::cmp::min(frame.len(), buf_len as usize);
+    unsafe {
+        ptr::copy_nonoverlapping(frame.as_ptr(), buf, copy_len);
+        *actual_len = frame.len() as u32;
+    }
+
+    SdkErrorCode::Success
+}
+
+/// 查询当前设备模式（Command=0, Streaming=1）
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn eskin_get_mode(handle: EskinDeviceHandle, out: *mut u32) -> SdkErrorCode {
+    if handle.is_null() || out.is_null() {
+        return SdkErrorCode::InvalidPointer;
+    }
+
+    let wrapper = unsafe { &*(handle as *const DeviceWrapper) };
+
+    let mode_val = match wrapper.device.mode() {
+        DeviceMode::Command => 0u32,
+        DeviceMode::Streaming => 1u32,
+    };
+    unsafe { *out = mode_val };
+    SdkErrorCode::Success
+}
+
+fn finger_sample_to_c(sample: &FingerSample) -> CFingerSample {
+    CFingerSample {
+        timestamp_us: sample.timestamp_us,
+        sequence: sample.sequence,
+        combined_force: combined_force_to_c(&sample.combined_forces),
+    }
+}
+
+fn combined_force_to_c(cf: &CombinedForce) -> CCombinedForce {
+    CCombinedForce {
+        module: cf.module as u32,
+        force: CForce3D {
+            fx: cf.force.fx,
+            fy: cf.force.fy,
+            fz: cf.force.fz,
+        },
+    }
+}

src/main.rs

@@ -1,21 +1,28 @@
-use eskin_finger_sdk::{config::DeviceConfig, device::{EskinDevice, EskinDeviceFunc, EskinDeviceInner}, transport::SerialPortTransport};
+use eskin_finger_sdk::{
+    config::DeviceConfig,
+    device::{EskinDevice, EskinDeviceFunc, EskinDeviceInner},
+    error::SdkError,
+    transport::SerialPortTransport,
+};
+use std::io::{self, BufRead};
 fn main() {
-    let transport = SerialPortTransport::new("/dev/ttyUSB0", 921600);
+    // let transport = SerialPortTransport::new("/dev/ttyUSB0", 921600);
-    let config = DeviceConfig::default();
+    // let config = DeviceConfig::default();
-    let mut device = EskinDeviceInner::new(config, Box::new(transport));
+    // let mut device = EskinDeviceInner::new(config, Box::new(transport));
-    device.open().unwrap();
+    // device.open().unwrap();
 
-    // let data = device.read_register(0x1C00, 168).unwrap();
+    // // let data = device.read_register(0x1C00, 168).unwrap();
-    // print_payload_data(&data);
+    // // print_payload_data(&data);
 
-    read_hdv(&mut device);
+    // read_hdv(&mut device);
-    read_check_group(&mut device);
+    // read_check_group(&mut device);
-    read_row(&mut device);
+    // read_row(&mut device);
-    write_col(&mut device, &[0x08]);
+    // write_col(&mut device, &[0x08]);
-    read_col(&mut device);
+    // read_col(&mut device);
-    read_config(&mut device);
+    // read_config(&mut device);
 
-    device.close().unwrap();
+    // device.close().unwrap();
+    stream_demo();
 }
 
 fn read_hdv(device: &mut EskinDeviceInner) {
@@ -28,7 +35,6 @@ fn read_check_group(device: &mut EskinDeviceInner) {
     print_payload_data(&group);
 }
 
-
 fn read_row(device: &mut EskinDeviceInner) {
     let row = device.read_register(0x0015, 1).unwrap();
     print_payload_data(&row);
@@ -48,13 +54,97 @@ fn read_config(device: &mut EskinDeviceInner) {
     print_payload_data(&conf);
 }
 
+/// Stream 模式演示：后台线程持续采集，主线程消费 sample
+/// 按 Enter 键停止流式采集
+fn stream_demo() {
+    let transport = SerialPortTransport::new("/dev/ttyUSB0", 921600);
+    let config = DeviceConfig::default();
+    let mut device = EskinDeviceInner::new(config, Box::new(transport));
+    device.open().unwrap();
+
+    println!("Hardware version: {}", device.read_hdw_version().unwrap());
+
+    // 进入 Streaming 模式
+    device.start_stream().unwrap();
+    println!("Stream started, mode: {:?}", device.mode());
+    println!("Press Enter to stop...");
+
+    // 用 stdin 阻塞线程来检测用户输入，实现优雅退出
+    let (tx, rx) = std::sync::mpsc::channel::<()>();
+    std::thread::spawn(move || {
+        let stdin = io::stdin();
+        stdin.lock().lines().next();
+        let _ = tx.send(());
+    });
+
+    let mut count: u64 = 0;
+    loop {
+        // 检查用户是否按了 Enter
+        if rx.try_recv().is_ok() {
+            println!("User requested stop.");
+            break;
+        }
+
+        match device.read_sample(200) {
+            Ok(sample) => {
+                count += 1;
+                if count % 5 == 0 {
+                    println!(
+                        "[#{count} seq={}] combined_force={:?}",
+                        sample.sequence, sample.combined_forces
+                    );
+
+                    match device.read_stream_frame(20) {
+                        Ok(frame) => {
+                            println!("raw_frame len={} [{}]", frame.len(), format_hex(&frame));
+                        }
+                        Err(SdkError::Timeout) => {
+                            println!("raw_frame timeout");
+                        }
+                        Err(e) => {
+                            eprintln!("read_stream_frame error: {e}");
+                        }
+                    }
+                }
+            }
+            Err(SdkError::Timeout) => continue,
+            Err(e) => {
+                eprintln!("read_sample error: {e}");
+                break;
+            }
+        }
+    }
+
+    // 回到 Command 模式
+    device.stop_stream().unwrap();
+    println!(
+        "Stream stopped, total samples: {count}, mode: {:?}",
+        device.mode()
+    );
+
+    // Stream 停止后，Command 操作恢复正常
+    println!("Row: {}", device.read_matrix_row().unwrap());
+
+    device.close().unwrap();
+}
+
 fn print_payload_data(data: &[u8]) {
     for (i, chunk) in data.chunks(2).enumerate() {
         if chunk.len() == 2 {
             let val = u16::from_le_bytes([chunk[0], chunk[1]]);
-            println!("  [{:3}] [{:02X}] [{:02X}] => {}", i, chunk[0], chunk[1], val);
+            println!(
+                "  [{:3}] [{:02X}] [{:02X}] => {}",
+                i, chunk[0], chunk[1], val
+            );
         } else {
             println!("  [{:3}] [{:02X}] (odd byte)", i, chunk[0]);
         }
     }
 }
+
+fn format_hex(data: &[u8]) -> String {
+    data.iter()
+        .map(|byte| format!("{byte:02X}"))
+        .collect::<Vec<_>>()
+        .join(" ")
+}

src/protocol.rs

@@ -346,7 +346,7 @@ impl ProtocolCodec for EskinProtocolCodec {
         }
 
         let data_len = Self::read_u16_le(frame, 2)? as usize;
-        let expected_len = 2 + 2 + data_len + FRAME_STATUS_LEN + FRAME_CRC_LEN;
+        let expected_len = 2 + 2 + data_len + FRAME_CRC_LEN;
 
         if frame.len() != expected_len {
             return Err(SdkError::FrameError(format!(
@@ -358,29 +358,37 @@ impl ProtocolCodec for EskinProtocolCodec {
         self.validate_crc(frame)?;
 
         let device_addr = frame[4];
+        let reserved = frame[5];
         let function = frame[6];
+
+        if reserved != 0x00 {
+            return Err(SdkError::FrameError(format!(
+                "invalid stream reserved byte: 0x{reserved:02X}"
+            )));
+        }
+
         let start_addr = Self::read_u32_le(frame, 7)?;
         let payload_len = Self::read_u16_le(frame, 11)? as usize;
-        if data_len != 9 + payload_len {
+        if data_len != 10 + payload_len {
             return Err(SdkError::FrameError(format!(
                 "stream frame data length mismatch: header data_len {data_len}, payload len {payload_len}"
             )));
         }
 
-        let payload_start = 13;
-        let payload_end = payload_start + payload_len;
-
-        let payload = frame
-            .get(payload_start..payload_end)
-            .ok_or_else(|| SdkError::FrameError("stream payload missing".into()))?
-            .to_vec();
-
         let status_offset = 13;
         let status_raw = *frame
             .get(status_offset)
             .ok_or_else(|| SdkError::FrameError("stream status missing".into()))?;
         let status = Self::status_from_u8(status_raw)?;
 
+        let payload_start = 14;
+        let payload_end = payload_start + payload_len;
+
+        let payload = frame
+            .get(payload_start..payload_end)
+            .ok_or_else(|| SdkError::FrameError("stream payload missing".into()))?
+            .to_vec();
+
         Ok(ProtocolFrame {
             start,
             device_addr,
@@ -404,12 +412,32 @@ mod tests {
         EskinProtocolCodec
     }
 
+    fn read_response_frame(payload: &[u8]) -> Vec<u8> {
+        let codec = codec();
+        let data_len = 10 + payload.len();
+        let mut frame = Vec::with_capacity(15 + payload.len());
+
+        frame.extend_from_slice(&FRAME_START_RESPONSE);
+        frame.extend_from_slice(&(data_len as u16).to_le_bytes());
+        frame.push(0x34);
+        frame.push(0x00);
+        frame.push(FUNC_RESPONSE_READ);
+        frame.extend_from_slice(&0x1C00u32.to_le_bytes());
+        frame.extend_from_slice(&(payload.len() as u16).to_le_bytes());
+        frame.push(0x00);
+        frame.extend_from_slice(payload);
+
+        let crc = codec.crc8(&frame);
+        frame.push(crc);
+        frame
+    }
+
     #[test]
     fn encode_read_request_has_correct_structure() {
         let req = ReadRequest {
             device_addr: 0x34,
             start_addr: 0x1C00,
-            read_byte_count: 168
+            read_byte_count: 168,
         };
 
         let frame = codec().encode_read_request(&req).unwrap();
@@ -438,4 +466,18 @@ mod tests {
 
         assert_eq!(frame.len(), 14);
     }
-}
+
+    #[test]
+    fn decode_stream_frame_reads_payload_after_status_byte() {
+        let payload = [0x10, 0x00, 0x20, 0x00];
+        let frame = read_response_frame(&payload);
+
+        let decoded = codec().decode_stream_frame(&frame).unwrap();
+
+        assert_eq!(decoded.device_addr, 0x34);
+        assert_eq!(decoded.function, FUNC_RESPONSE_READ);
+        assert_eq!(decoded.start_addr, 0x1C00);
+        assert_eq!(decoded.status, Some(DeviceStatus::Success));
+        assert_eq!(decoded.payload, payload);
+    }
+}

src/register.rs

@@ -1,7 +1,7 @@
 use crate::{
     config::DeviceInfo,
     error::SdkError,
-        types::{CombinedForce, DistributionForce, Force3D, ForcePoint, ModuleError, SensorModule},
+    types::{CombinedForce, DistributionForce, Force3D, ForcePoint, ModuleError, SensorModule},
 };
 
 pub const REG_SERIAL_NUMBER: u32 = 0x0000;
@@ -12,7 +12,7 @@ pub const REG_L_LINE: u32 = 0x0012;
 pub const REG_H_LINE: u32 = 0x0013;
 pub const REG_PRODUCT_CONFIG_1: u32 = 0x0030;
 pub const REG_PRODUCT_CONFIG_2: u32 = 0x0032;
-pub const REG_COMBINED_FORCE: u32 = 0x0500;
+pub const REG_COMBINED_FORCE: u32 = 0x1C00;
 pub const REG_MODULE_ERROR: u32 = 0x0700;
 pub const REG_DISTRIBUTION_FORCE_BASE: u32 = 0x1000;
 pub const REG_PROCESSED_VALUE_BASE: u32 = 0x2000;
@@ -146,33 +146,45 @@ impl RegisterMap for EskinRegisterMap {
     }
 }
 
+pub fn parse_combined_forces(raw: &[u8], addr: u32) -> Result<CombinedForce, SdkError> {
+    // println!("{:02X?}", raw);
+    // const MODULE_COUNT: usize = 28;
+    // const BYTES_PER_MODULE: usize = 6;
 
-pub fn parse_combined_forces(raw: &[u8]) -> Result<Vec<CombinedForce>, SdkError> {
+    // if raw.len() < MODULE_COUNT * BYTES_PER_MODULE {
-    const MODULE_COUNT: usize = 28;
+    //     return Err(SdkError::FrameError(format!(
-    const BYTES_PER_MODULE: usize = 6;
+    //         "combined force raw too short: expected {} bytes, got {}",
+    //         MODULE_COUNT * BYTES_PER_MODULE,
+    //         raw.len()
+    //     )));
+    // }
 
-    if raw.len() < MODULE_COUNT * BYTES_PER_MODULE {
+    // let mut forces = Vec::with_capacity(MODULE_COUNT);
-        return Err(SdkError::FrameError(format!(
+    // for i in 0..MODULE_COUNT {
-            "combined force raw too short: expected {} bytes, got {}",
+    //     let offset =  i * BYTES_PER_MODULE;
-            MODULE_COUNT * BYTES_PER_MODULE,
+    //     let fx = i16::from_le_bytes([raw[offset], raw[offset + 1]]);
-            raw.len()
+    //     let fy = i16::from_le_bytes([raw[offset + 2], raw[offset + 3]]);
-        )));
+    //     let fz = i16::from_le_bytes([raw[offset + 4], raw[offset + 5]]);
-    }
 
-    let mut forces = Vec::with_capacity(MODULE_COUNT);
+    //     forces.push(CombinedForce {
-    for i in 0..MODULE_COUNT {
+    //         module: SensorModule::from_index(i as u8),
-        let offset =  i * BYTES_PER_MODULE;
+    //         force: Force3D { fx, fy, fz },
-        let fx = i16::from_le_bytes([raw[offset], raw[offset + 1]]);
+    //     });
-        let fy = i16::from_le_bytes([raw[offset + 2], raw[offset + 3]]);
+    // }
-        let fz = i16::from_le_bytes([raw[offset + 4], raw[offset + 5]]);
+    let comb_force: u32 = raw
+        .chunks(2)
+        .map(|ch| u16::from_le_bytes([ch[0], ch[1]]) as u32)
+        .sum();
+    let force = CombinedForce {
+        module: addr.into(),
+        force: Force3D {
+            fx: 0,
+            fy: 0,
+            fz: comb_force,
+        },
+    };
 
-        forces.push(CombinedForce {
+    Ok(force)
-            module: SensorModule::from_index(i as u8),
-            force: Force3D { fx, fy, fz },
-        });
-    }
-
-    Ok(forces)
 }
 
 pub fn parse_module_errors(raw: &[u8]) -> Result<Vec<ModuleError>, SdkError> {
@@ -201,4 +213,4 @@ pub fn parse_module_errors(raw: &[u8]) -> Result<Vec<ModuleError>, SdkError> {
     }
 
     Ok(errors)
-}
+}

src/stream.rs

@@ -3,7 +3,6 @@ use std::sync::{
     atomic::{AtomicBool, Ordering},
 };
 
-use crate::register::{REG_COMBINED_FORCE, REG_MODULE_ERROR};
 use chrono::Duration;
 
 use crate::{
@@ -14,9 +13,14 @@ use crate::{
     types::{FingerSample, SensorModule},
 };
 
-use crate::protocol::{FRAME_CRC_LEN, FRAME_START_RESPONSE, FRAME_STATUS_LEN, ReadRequest};
+use crate::protocol::{FRAME_CRC_LEN, FRAME_START_RESPONSE, ReadRequest};
 use std::thread::{self, JoinHandle};
-use std::time::Duration as StdDuration;
+use std::time::{Duration as StdDuration, Instant};
+
+const STREAM_READ_BYTE_COUNT: u16 = 168;
+const STREAM_RESPONSE_DATA_OVERHEAD: usize = 10;
+const STREAM_FRAME_PREFIX_LEN: usize = 14;
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum StreamMode {
     Polling,
@@ -31,6 +35,7 @@ pub struct StreamConfig {
     pub poll_interval_ms: u32,
     pub device_addr: u8,
     pub read_timeout_ms: u32,
+    pub finger_addr: u32,
 }
 
 impl Default for StreamConfig {
@@ -42,6 +47,7 @@ impl Default for StreamConfig {
             poll_interval_ms: 10,
             device_addr: 0x34,
             read_timeout_ms: 100,
+            finger_addr: 0x1C00,
         }
     }
 }
@@ -51,6 +57,7 @@ pub trait StreamController: Send {
     fn stop(&mut self) -> Result<(), SdkError>;
     fn is_running(&self) -> bool;
     fn next_sample(&self, timeout_ms: u32) -> Result<FingerSample, SdkError>;
+    fn next_raw_frame(&self, timeout_ms: u32) -> Result<Vec<u8>, SdkError>;
     fn next_event(&self, timeout_ms: u32) -> Result<DeviceEvent, SdkError>;
 }
 
@@ -92,12 +99,13 @@ impl StreamController for StreamRuntime {
             return Err(SdkError::AlreadyStreaming);
         }
 
-        let collector = make_collector(&config, Arc::clone(&self.transport));
+        // Old synchronous collector path:
+        // let collector = make_collector(&config, Arc::clone(&self.transport));
         let worker = StreamWorker::new(
             Arc::clone(&self.running),
             Arc::clone(&self.channels),
+            Arc::clone(&self.transport),
             config.clone(),
-            collector,
         )
         .spawn();
 
@@ -131,6 +139,10 @@ impl StreamController for StreamRuntime {
         self.channels.recv_sample(timeout_ms)
     }
 
+    fn next_raw_frame(&self, timeout_ms: u32) -> Result<Vec<u8>, SdkError> {
+        self.channels.recv_raw_frame(timeout_ms)
+    }
+
     fn next_event(&self, timeout_ms: u32) -> Result<DeviceEvent, SdkError> {
         self.channels.recv_event(timeout_ms)
     }
@@ -139,22 +151,30 @@ impl StreamController for StreamRuntime {
 pub struct StreamWorker {
     running: Arc<AtomicBool>,
     channels: Arc<ChannelManager>,
+    transport: SharedSerialTransport,
     config: StreamConfig,
-    collector: Box<dyn SampleCollector>,
+    codec: Box<dyn ProtocolCodec>,
+    rx_buffer: Vec<u8>,
+    sequence: u32,
+    next_request_at: Instant,
 }
 
 impl StreamWorker {
     pub fn new(
         running: Arc<AtomicBool>,
         channels: Arc<ChannelManager>,
+        transport: SharedSerialTransport,
         config: StreamConfig,
-        collector: Box<dyn SampleCollector>,
     ) -> Self {
         Self {
             running,
             channels,
+            transport,
             config,
-            collector,
+            codec: Box::new(EskinProtocolCodec),
+            rx_buffer: Vec::with_capacity(512),
+            sequence: 0,
+            next_request_at: Instant::now(),
         }
     }
 
@@ -173,30 +193,151 @@ impl StreamWorker {
                 break;
             }
 
-            thread::sleep(StdDuration::from_millis(
+            thread::sleep(StdDuration::from_millis(1));
-                self.config.poll_interval_ms as u64,
-            ));
         }
     }
 
     fn tick(&mut self) -> Result<(), SdkError> {
-        // let _transport = self
+        // Old synchronous polling path kept for reference:
-        //     .transport
+        //
-        //     .lock()
+        // let Some(sample) = self.collector.collect_once()? else {
-        //     .map_err(|_| SdkError::InternalError("transport mutex poisoned".into()))?;
+        //     return Ok(());
+        // };
+        // self.channels.send_sample(sample)?;
 
-        let Some(sample) = self.collector.collect_once()? else {
+        self.send_request_if_due()?;
-            return Ok(());
+        self.read_and_decode_available()?;
-        };
-        self.channels.send_sample(sample)?;
         Ok(())
-        // TODO:
+    }
-        // 1. encode read request
+
-        // 2. transport.write()
+    fn send_request_if_due(&mut self) -> Result<(), SdkError> {
-        // 3. transport.read()
+        if Instant::now() < self.next_request_at {
-        // 4. protocol.decode()
+            return Ok(());
-        // 5. register parse
+        }
-        // 6. channels.send_sample()
+
+        let request = ReadRequest {
+            device_addr: self.config.device_addr,
+            start_addr: self.config.finger_addr,
+            read_byte_count: STREAM_READ_BYTE_COUNT,
+        };
+        let request_frame = self.codec.encode_read_request(&request)?;
+
+        {
+            let mut transport = self
+                .transport
+                .lock()
+                .map_err(|_| SdkError::InternalError("transport mutex poisoned".into()))?;
+            transport.write(&request_frame)?;
+        }
+
+        let interval = StdDuration::from_millis(self.config.poll_interval_ms as u64);
+        self.next_request_at = Instant::now() + interval.max(StdDuration::from_millis(1));
+        Ok(())
+    }
+
+    fn read_and_decode_available(&mut self) -> Result<(), SdkError> {
+        let mut buf = [0u8; 256];
+        let read_result = {
+            let mut transport = self
+                .transport
+                .lock()
+                .map_err(|_| SdkError::InternalError("transport mutex poisoned".into()))?;
+            transport.read(&mut buf, Duration::milliseconds(1))
+        };
+
+        match read_result {
+            Ok(0) | Err(SdkError::Timeout) => return Ok(()),
+            Ok(n) => self.rx_buffer.extend_from_slice(&buf[..n]),
+            Err(err) => return Err(err),
+        }
+
+        while let Some(frame) = self.pop_next_frame()? {
+            self.channels.send_raw_frame(frame.clone())?;
+
+            let response = self.codec.decode_read_response(&frame)?;
+            if response.start_addr != self.config.finger_addr {
+                continue;
+            }
+
+            let combined_forces =
+                crate::register::parse_combined_forces(&response.data, response.start_addr)?;
+            let sample = FingerSample {
+                timestamp_us: chrono::Utc::now().timestamp_micros() as u64,
+                sequence: self.next_sequence(),
+                combined_forces,
+            };
+            self.channels.send_sample(sample)?;
+        }
+
+        Ok(())
+    }
+
+    fn pop_next_frame(&mut self) -> Result<Option<Vec<u8>>, SdkError> {
+        pop_next_stream_frame(&mut self.rx_buffer, self.codec.as_ref())
+    }
+
+    fn next_sequence(&mut self) -> u32 {
+        let sequence = self.sequence;
+        self.sequence = self.sequence.wrapping_add(1);
+        sequence
+    }
+}
+
+fn pop_next_stream_frame(
+    rx_buffer: &mut Vec<u8>,
+    codec: &dyn ProtocolCodec,
+) -> Result<Option<Vec<u8>>, SdkError> {
+    loop {
+        let Some(start) = rx_buffer
+            .windows(FRAME_START_RESPONSE.len())
+            .position(|window| window == FRAME_START_RESPONSE)
+        else {
+            rx_buffer.clear();
+            return Ok(None);
+        };
+
+        if start > 0 {
+            rx_buffer.drain(..start);
+        }
+
+        if rx_buffer.len() < 4 {
+            return Ok(None);
+        }
+
+        let data_len = u16::from_le_bytes([rx_buffer[2], rx_buffer[3]]) as usize;
+        let frame_len = 4 + data_len + FRAME_CRC_LEN;
+
+        if data_len < STREAM_RESPONSE_DATA_OVERHEAD
+            || frame_len < crate::protocol::MIN_RESPONSE_FRAME_LEN
+        {
+            rx_buffer.drain(..1);
+            continue;
+        }
+
+        if rx_buffer.len() < STREAM_FRAME_PREFIX_LEN {
+            return Ok(None);
+        }
+
+        let expected_data_len = u16::from_le_bytes([rx_buffer[11], rx_buffer[12]]) as usize;
+        if expected_data_len != STREAM_READ_BYTE_COUNT as usize
+            || data_len != STREAM_RESPONSE_DATA_OVERHEAD + expected_data_len
+        {
+            rx_buffer.drain(..1);
+            continue;
+        }
+
+        if rx_buffer.len() < frame_len {
+            return Ok(None);
+        }
+
+        let expected_crc = rx_buffer[frame_len - 1];
+        let actual_crc = codec.crc8(&rx_buffer[..frame_len - 1]);
+        if expected_crc != actual_crc {
+            rx_buffer.drain(..1);
+            continue;
+        }
+
+        return Ok(Some(rx_buffer.drain(..frame_len).collect()));
     }
 }
 
@@ -277,7 +418,7 @@ impl PollingSampleCollector {
         }
 
         let data_len = u16::from_le_bytes([header[2], header[3]]) as usize;
-        let total_len = 4 + data_len + FRAME_STATUS_LEN + FRAME_CRC_LEN;
+        let total_len = 4 + data_len + FRAME_CRC_LEN;
 
         let mut frame = vec![0u8; total_len];
         frame[..4].copy_from_slice(&header);
@@ -296,7 +437,6 @@ impl PollingSampleCollector {
         };
 
         let request_frame = self.codec.encode_read_request(&request)?;
-
         let response_frame = {
             let mut transport = self
                 .transport
@@ -317,11 +457,10 @@ impl SampleCollector for PollingSampleCollector {
     fn collect_once(&mut self) -> Result<Option<FingerSample>, SdkError> {
         let sequence = self.next_sequence();
 
-        let combined_force_raw = self.read_register(REG_COMBINED_FORCE, 168)?;
+        let combined_force_raw = self.read_register(self.config.finger_addr, 168)?;
-        let module_error_raw = self.read_register(REG_MODULE_ERROR, 56)?;
 
-        let combined_forces = crate::register::parse_combined_forces(&combined_force_raw)?;
+        let combined_forces =
-        let module_errors = crate::register::parse_module_errors(&module_error_raw)?;
+            crate::register::parse_combined_forces(&combined_force_raw, self.config.finger_addr)?;
 
         let now = chrono::Utc::now().timestamp_micros() as u64;
 
@@ -329,14 +468,15 @@ impl SampleCollector for PollingSampleCollector {
             timestamp_us: now,
             sequence,
             combined_forces,
-            distribution_forces: Vec::new(),
+            // distribution_forces: Vec::new(),
-            module_errors
+            // module_errors
         };
 
         Ok(Some(sample))
     }
 }
 
+#[allow(dead_code)]
 fn make_collector(
     config: &StreamConfig,
     transport: SharedSerialTransport,
@@ -346,3 +486,79 @@ fn make_collector(
         StreamMode::AutoDistribution => Box::new(NoopSampleCollector),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn stream_frame(payload_seed: u8) -> Vec<u8> {
+        let codec = EskinProtocolCodec;
+        let payload = vec![payload_seed; STREAM_READ_BYTE_COUNT as usize];
+        let data_len = STREAM_RESPONSE_DATA_OVERHEAD + payload.len();
+
+        let mut frame = Vec::with_capacity(STREAM_FRAME_PREFIX_LEN + payload.len() + 1);
+        frame.extend_from_slice(&FRAME_START_RESPONSE);
+        frame.extend_from_slice(&(data_len as u16).to_le_bytes());
+        frame.push(0x34);
+        frame.push(0x00);
+        frame.push(crate::protocol::FUNC_RESPONSE_READ);
+        frame.extend_from_slice(&0x1C00u32.to_le_bytes());
+        frame.extend_from_slice(&(payload.len() as u16).to_le_bytes());
+        frame.push(0x00);
+        frame.extend_from_slice(&payload);
+
+        let crc = codec.crc8(&frame);
+        frame.push(crc);
+        frame
+    }
+
+    #[test]
+    fn pop_next_stream_frame_keeps_partial_frame_buffered() {
+        let codec = EskinProtocolCodec;
+        let frame = stream_frame(0x11);
+        let mut buffer = frame[..20].to_vec();
+
+        let popped = pop_next_stream_frame(&mut buffer, &codec).unwrap();
+
+        assert!(popped.is_none());
+        assert_eq!(buffer, frame[..20]);
+    }
+
+    #[test]
+    fn pop_next_stream_frame_splits_sticky_frames() {
+        let codec = EskinProtocolCodec;
+        let first = stream_frame(0x11);
+        let second = stream_frame(0x22);
+        let mut buffer = Vec::new();
+        buffer.extend_from_slice(&first);
+        buffer.extend_from_slice(&second);
+
+        assert_eq!(
+            pop_next_stream_frame(&mut buffer, &codec).unwrap(),
+            Some(first)
+        );
+        assert_eq!(
+            pop_next_stream_frame(&mut buffer, &codec).unwrap(),
+            Some(second)
+        );
+        assert!(buffer.is_empty());
+    }
+
+    #[test]
+    fn pop_next_stream_frame_resyncs_after_bad_crc() {
+        let codec = EskinProtocolCodec;
+        let mut bad = stream_frame(0x11);
+        let good = stream_frame(0x22);
+        let last = bad.len() - 1;
+        bad[last] ^= 0xFF;
+
+        let mut buffer = bad;
+        buffer.extend_from_slice(&good);
+
+        assert_eq!(
+            pop_next_stream_frame(&mut buffer, &codec).unwrap(),
+            Some(good)
+        );
+        assert!(buffer.is_empty());
+    }
+}

src/types.rs

@@ -3,9 +3,9 @@ use serde::{Deserialize, Serialize};
 #[repr(C)]
 #[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
 pub struct Force3D {
-    pub fx: i16,
+    pub fx: u32,
-    pub fy: i16,
+    pub fy: u32,
-    pub fz: i16,
+    pub fz: u32,
 }
 
 #[repr(C)]
@@ -90,6 +90,33 @@ impl SensorModule {
     }
 }
 
+impl From<u32> for SensorModule {
+    fn from(value: u32) -> Self {
+        match value {
+            0x1000 => SensorModule::ThumbProximal,
+            0x1200 => SensorModule::ThumbMiddle,
+            0x1400 => SensorModule::ThumbTip,
+            0x1600 => SensorModule::ThumbNail,
+            0x1800 => SensorModule::IndexProximal,
+            0x1A00 => SensorModule::IndexMiddle,
+            0x1C00 => SensorModule::IndexTip,
+            0x1E00 => SensorModule::IndexNail,
+            0x2000 => SensorModule::MiddleProximal,
+            0x2200 => SensorModule::MiddleMiddle,
+            0x2400 => SensorModule::MiddleTip,
+            0x2600 => SensorModule::MiddleNail,
+            0x2800 => SensorModule::RingProximal,
+            0x2A00 => SensorModule::RingMiddle,
+            0x2C00 => SensorModule::RingTip,
+            0x2E00 => SensorModule::RingNail,
+            0x3000 => SensorModule::PinkyProximal,
+            0x3200 => SensorModule::PinkyMiddle,
+            0x3400 => SensorModule::PinkyTip,
+            0x3600 => SensorModule::PinkyNail,
+            _ => SensorModule::IndexTip,
+        }
+    }
+}
 
 pub const SENSOR_MODULE_COUNT: usize = 28;
 
@@ -113,9 +140,9 @@ pub struct CombinedForce {
 pub struct FingerSample {
     pub timestamp_us: u64,
     pub sequence: u32,
-    pub combined_forces: Vec<CombinedForce>,
+    pub combined_forces: CombinedForce,
-    pub distribution_forces: Vec<DistributionForce>,
+    // pub distribution_forces: Vec<DistributionForce>,
-    pub module_errors: Vec<ModuleError>,
+    // pub module_errors: Vec<ModuleError>,
 }
 
 #[repr(C)]