# SMRF-T 8Ch

**Repository Path**: johnzchgrd/smrf-t_8ch

## Basic Information

- **Project Name**: SMRF-T 8Ch
- **Description**: SMRF-T 8 通道 Python SDK
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-21
- **Last Updated**: 2026-10-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SMRF-T 8 通道 Python SDK

独立实现厂家 USB HID 协议，无需运行厂家上位机。提供八路温度/原始电势读取、设备配置查询、主机侧通道设置、冷端补偿、连续采样及 CSV/JSON 导出。

**SMRF Studio 桌面工作台。** 八路实时温度卡片、交互曲线、统计明细、主机侧设置、温度报警及 CSV 记录；启动后自动提供本地 MCP 服务，让 Agent 共用 GUI 的设备连接。功能权限可在界面逐项配置并记忆，支持一键复制 Agent 配置。详见 [GUI 使用说明](docs/gui.md)及 [MCP 接入说明](docs/mcp.md)。

![SMRF Studio 演示模式界面](docs/images/studio.png)

```powershell
uv sync --locked --extra gui
uv run --no-sync smrf-studio
```

本工作区可直接双击 `SMRF-Studio.cmd`。无设备时可运行 `smrf-studio --demo` 查看明确标识的模拟信号。

**已用 SMRFCT08B 实机验证。** 规格书中的 CT08A 尚未实机验证。要求 Python 3.10+；当前硬件验收环境为 Windows 11。其他操作系统通过 HIDAPI 适配，尚未实机验证。

## 安装与首次读取

在仓库目录执行：

```powershell
python -m pip install .
smrf-t list
smrf-t read --count 5 --interval 1
```

本工作区已准备 `.venv`，可直接运行：

```powershell
.venv\Scripts\python.exe examples\read_once.py
.venv\Scripts\smrf-t.exe read --count 20 --interval 0.1 --csv temperatures.csv
```

```python
from smrf_t import SMRFT8, discover

for info in discover():
    print(info.product_name, info.serial_number)

with SMRFT8.open() as instrument:
    measurement = instrument.read()
    print(measurement.temperatures)       # CH1..CH8，单位 °C
    print(measurement.cold_junction_c)    # 实测冷端温度
    print(measurement.timestamp)          # 主机接收时间，UTC
```

多台设备必须用 `SMRFT8.open(serial_number="YOUR_SERIAL")` 或 `path=info.path` 选择。请让一个进程独占仪器协议，并关闭使用该仪器的厂家 GUI；协议没有请求编号，无法可靠区分其他客户端的同类请求。

## 连续采样与导出

```python
with SMRFT8.open() as instrument:
    for measurement in instrument.iter_measurements(interval=0.1, count=100):
        print(measurement.temperatures)
```

```powershell
smrf-t list --json
smrf-t config --serial YOUR_SERIAL --json
smrf-t read --count 100 --interval 0.1 --csv measurements.csv
smrf-t read --count 0 --interval 1 --json
```

CLI 的 `--count 0` 持续采集直到 Ctrl+C。JSON 使用每行一条记录的 JSON Lines；CSV 含 UTC 时间、冷端、八路温度和通道状态，拒绝覆盖已有文件。退出码：0 成功，2 参数/设备错误，130 用户中断。

设备临时采样周期支持 0.1、0.5、1 秒；更长间隔由主机计时。设备逐路测量，没有设备时间戳或采样编号；连续结果可能相同，0.1 秒轮询不等于八路同时采样或硬实时保证。

## 通道设置与补偿

支持 `DISABLED / K / J / T / S / N / E / R`。偏移步长为 0.1 °C，范围 −12.8..12.7 °C。可读取设备设置，或在主机侧覆盖换算参数：

```python
from dataclasses import replace
from smrf_t import DeviceConfig, SMRFT8, ThermocoupleType

with SMRFT8.open() as instrument:
    channels = list(instrument.read_configuration().channels)
    channels[0] = replace(channels[0], sensor_type=ThermocoupleType.K, offset_c=0.5)
    settings = DeviceConfig(tuple(channels))
    measurement = instrument.read(configuration=settings)
    # 连续采样：instrument.iter_measurements(configuration=settings, count=100)
```

显式配置只作用于本次读取/迭代的数值换算，不修改缓存的设备配置。省略时使用设备查询结果。

**当前版本不提供持久化配置写入。** 真机验证出现部分字段生效、读回不一致；相关尝试已移入 `.local/`。打开、采集和关闭都不写设备持久化设置。

```python
from smrf_t import Compensation, SMRFT8

with SMRFT8.open(compensation=Compensation(cold_junction_c=25.0)) as instrument:
    measurement = instrument.read()      # 显式使用 25 °C 参考冷端
    raw = instrument.read_raw()           # 原始计数、电势、冷端、完整 HID 报文
```

默认使用实测冷端，线长默认 2 m（零额外修正）。`Compensation(cable_length_m=...)` 是显式主机参数，其经验公式和边界见[协议说明](docs/protocol.md)，未做不同线长的物理标定。

## 数据与错误

设备返回的是电势，SDK 使用 [NIST ITS-90 参考表](https://doi.org/10.6028/NIST.MONO.175) 进行线性插值、冷端电势叠加和反查，输出分辨率为 0.01 °C。分辨率不代表测量准确度。

停用通道为 `status="disabled"`，范围异常为 `status="over_range"`，对应 `celsius=None`；SDK 不将它们当成零度，也不将过量程直接认定为探头断线。

低层严格检查头部、长度和 XOR。会话在总响应超时内至多发送三次只读查询，丢弃无效报文；持续失败抛出 `ChecksumError` / `ProtocolError` / `DeviceTimeoutError`，系统连接错误抛出 `TransportError`。默认响应超时 2 秒；它不是硬实时期限。`smrf-t --debug read` 可查看收发与恢复日志。

## 开发与测试

```powershell
uv sync --locked --extra gui
uv run pytest
uv run ruff check src tests tools examples
uv run ruff format --check src tests tools examples
uv run mypy src
uv build
```

离线测试默认不操作设备。显式启用真机测试：

```powershell
uv run pytest --run-hardware tests/test_hardware.py --hardware-report .local/hardware-validation.json
```

多台设备可设置 `SMRF_TEST_SERIAL`。真机测试仅采集和查询，不写持久化配置。采用 `src/` 布局、PEP 517/621 打包、类型标注、`py.typed` 和依赖锁。CI 配置覆盖 Windows/Linux、Python 3.10/3.12/3.14；推送仓库后才会运行远端 CI。

- [桌面 GUI](docs/gui.md)、[本地 MCP 服务](docs/mcp.md)、[API](docs/api.md)、[USB 协议与数值换算](docs/protocol.md)
- [实机验收与限制](docs/hardware-validation.md)
- [版本记录](CHANGELOG.md)、[MIT 许可证](LICENSE)、[资料来源](NOTICE)

厂家 EXE/PDF 仅保留在本地 `doc/`；Ghidra 工程、反编译代码、函数地址、分析脚本和原始采集日志保存在 `.local/`，均排除在 Git 与发行包之外。公开文档只保留 SDK 用法、协议说明与验证结论。SDK 运行不依赖这些私有资料。