BodyBalanceEvaluation/backend/tests/SMiTSense_DLL_Analysis.md

# SMiTSense足部压力传感器DLL分析报告

## 概述

本文档分析了`SMiTSenseUsb-F3.0.dll`和`SMiTSenseUsb-F3.0.lib`文件，并提供了Python调用接口的实现。

## DLL文件分析

### 文件信息
- **DLL文件**: `SMiTSenseUsb-F3.0.dll`
- **库文件**: `SMiTSenseUsb-F3.0.lib`
- **版本**: F3.0
- **用途**: SMiTSense足部压力传感器USB通信驱动

### 导出函数列表

通过分析`.lib`文件，发现以下导出函数：

| 函数名 | 功能描述 | 参数说明 |
|--------|----------|----------|
| `fpms_usb_init` | 初始化USB连接 | 无参数 |
| `fpms_usb_get_device_list` | 获取设备列表 | 设备数量指针 |
| `fpms_usb_open` | 打开指定设备 | 设备ID |
| `fpms_usb_close` | 关闭设备连接 | 设备句柄 |
| `fpms_usb_read_frame` | 读取压力数据帧 | 设备句柄、数据缓冲区、传感器数量 |
| `fpms_usb_get_sensitivity` | 获取传感器灵敏度 | 设备句柄、灵敏度指针 |
| `fpms_usb_config_sensitivity` | 配置传感器灵敏度 | 设备句柄、灵敏度值 |

### 函数调用流程

```
1. fpms_usb_init()           // 初始化USB子系统
2. fpms_usb_get_device_list() // 获取可用设备
3. fpms_usb_open()           // 打开设备
4. fpms_usb_get_sensitivity() // 获取当前灵敏度（可选）
5. fpms_usb_config_sensitivity() // 设置灵敏度（可选）
6. fpms_usb_read_frame()     // 循环读取压力数据
7. fpms_usb_close()          // 关闭设备
```

## Python接口实现

### 核心类：SMiTSensePressureSensor

```python
class SMiTSensePressureSensor:
    def __init__(self, dll_path=None)
    def initialize(self)
    def get_device_list()
    def connect(self, device_id=0)
    def disconnect(self)
    def read_pressure_data(self, sensor_count=16)
    def get_sensitivity()
    def set_sensitivity(self, sensitivity_value)
    def get_foot_pressure_zones(self, pressure_data)
```

### 使用示例

```python
from test_smitsense_dll import SMiTSensePressureSensor

# 创建传感器实例
sensor = SMiTSensePressureSensor()

# 初始化并连接
if sensor.initialize():
    devices = sensor.get_device_list()
    if devices and sensor.connect(devices[0]):
        # 读取压力数据
        pressure_data = sensor.read_pressure_data()
        if pressure_data:
            foot_zones = sensor.get_foot_pressure_zones(pressure_data)
            print(f"左脚压力: {foot_zones['left_total']}")
            print(f"右脚压力: {foot_zones['right_total']}")
        
        # 断开连接
        sensor.disconnect()
```

## 测试程序说明

### 1. test_smitsense_dll.py

**功能**: 完整的DLL接口封装和测试

**特性**:
- 完整的ctypes函数签名定义
- 错误处理和日志记录
- 足部压力区域数据处理
- 设备连接管理

**运行方式**:
```bash
python test_smitsense_dll.py
```

### 2. smitsense_demo.py

**功能**: 简化的演示程序

**特性**:
- 实时压力监控
- 简单的平衡分析
- 用户友好的界面
- 安全的设备断开

**运行方式**:
```bash
python smitsense_demo.py
python smitsense_demo.py --help  # 查看使用说明
```

## 数据格式说明

### 原始压力数据
- **类型**: float数组
- **长度**: 16个传感器点（可配置）
- **单位**: 压力值（具体单位取决于传感器校准）
- **频率**: 最高支持约50Hz采样

### 足部区域数据
```python
{
    'left_front': float,    # 左脚前部压力
    'left_rear': float,     # 左脚后部压力
    'right_front': float,   # 右脚前部压力
    'right_rear': float,    # 右脚后部压力
    'left_total': float,    # 左脚总压力
    'right_total': float,   # 右脚总压力
    'total_pressure': float, # 总压力
    'raw_data': list        # 原始16点数据
}
```

### 传感器布局假设
```
左脚布局:          右脚布局:
[0] [1]           [8]  [9]
[2] [3]           [10] [11]
[4] [5]           [12] [13]
[6] [7]           [14] [15]
前部  后部         前部  后部
```

## 集成到现有系统

### 替换MockPressureDevice

在`device_manager.py`中，可以用真实的SMiTSense传感器替换模拟设备：

```python
# 原代码
self.pressure_device = MockPressureDevice()

# 替换为
from tests.test_smitsense_dll import SMiTSensePressureSensor
self.pressure_device = SMiTSensePressureSensor()
if self.pressure_device.initialize():
    devices = self.pressure_device.get_device_list()
    if devices:
        self.pressure_device.connect(devices[0])
```

### 数据格式适配

需要修改`read_data()`方法以匹配现有的数据格式：

```python
def read_data(self):
    pressure_data = self.pressure_device.read_pressure_data()
    if pressure_data:
        foot_zones = self.pressure_device.get_foot_pressure_zones(pressure_data)
        return {
            'foot_pressure': foot_zones,
            'timestamp': datetime.now().isoformat(),
            'pressure_image': ''  # 如需要可生成压力分布图
        }
    return None
```

## 故障排除

### 常见问题

1. **DLL加载失败**
   - 检查DLL文件路径
   - 确保系统架构匹配（32位/64位）
   - 检查依赖的运行时库

2. **设备未找到**
   - 检查USB连接
   - 确认设备驱动已安装
   - 检查设备是否被其他程序占用

3. **数据读取失败**
   - 检查设备连接状态
   - 确认传感器校准状态
   - 检查USB通信稳定性

4. **函数调用错误**
   - 检查函数参数类型
   - 确认函数调用顺序
   - 查看错误码含义

### 调试建议

1. **启用详细日志**
   ```python
   import logging
   logging.basicConfig(level=logging.DEBUG)
   ```

2. **检查返回值**
   - 所有函数都返回错误码
   - 0通常表示成功
   - 非0值表示不同的错误类型

3. **使用try-except**
   - 捕获ctypes相关异常
   - 处理设备断开情况
   - 记录详细错误信息

## 性能考虑

### 采样频率
- **推荐频率**: 20-50Hz
- **最大频率**: 约100Hz（取决于USB带宽）
- **实际应用**: 根据应用需求调整

### 内存使用
- **数据缓冲**: 每次读取约64字节（16个float）
- **内存泄漏**: 确保正确释放设备句柄
- **垃圾回收**: 定期清理压力数据缓存

### CPU占用
- **主要开销**: USB通信和数据转换
- **优化建议**: 使用独立线程进行数据采集
- **批处理**: 可考虑批量读取多帧数据

## 扩展功能

### 可能的增强
1. **数据滤波**: 实现低通滤波减少噪声
2. **校准功能**: 自动零点校准和增益调整
3. **数据记录**: 保存压力数据到文件
4. **可视化**: 实时压力分布图显示
5. **多设备**: 支持同时连接多个传感器

### 与现有系统集成
1. **WebSocket推流**: 集成到现有的实时数据推流
2. **数据库存储**: 保存压力数据到SQLite
3. **前端显示**: 在Vue界面中显示压力分布
4. **报告生成**: 包含压力分析的PDF报告

## 总结

SMiTSenseUsb-F3.0.dll提供了完整的足部压力传感器接口，通过Python ctypes可以实现有效的调用。测试程序验证了基本功能，可以作为集成到现有平衡体态检测系统的基础。

建议在实际部署前进行充分的硬件测试，确保传感器校准准确，数据采集稳定。