# 无硬件也能运行的读取示例

先认识夹爪或滑台的直线位置，再学习关节角度。下面命令都从仓库根目录执行，建议 Python 3.10 或更新版本。默认演示不安装第三方依赖，不访问串口：

```powershell
python software/examples/read_sensor.py
python software/examples/read_sensor.py --demo --profile line --count 5
python software/examples/read_sensor.py --demo --profile encoder --count 5
```

输出为每行一个 JSON，保留协议整数、显示单位、SI 单位、三路 ADC、标志和主机时间。`source=simulated_not_hardware` 明确表示模拟数据。模拟波形用于解释数据流和单位，未复现实际磁铁、噪声、安装误差或精度。

接入一块已配置好的传感器和自动收发 USB-RS485 适配器后，只安装串口依赖：

```powershell
python -m pip install pyserial
python software/examples/read_sensor.py --port COM7 --id 1 --baud 115200 --count 20
python software/examples/read_sensor.py --port COM7 --id 1 --count 0 --interval-ms 100
```

将 `COM7` 换成实际端口。Linux 端口示例为 `/dev/ttyUSB0`。真实串口路径先用 `GET_INFO` 读取测量类型，然后只发 `GET_DATA`；不写配置、不切模式、不改零点。固件出厂默认是角度模式，`--profile` 只影响演示，真实模式以设备返回值为准。先按 [直线实验](../../wiki/Labs.md) 完成硬件模式配置后再读直线数据。

默认读取 20 帧后退出；`--count 0` 表示持续读取，Ctrl+C 停止。`--interval-ms` 是读完一帧后的等待时间，实际间隔还包含串口传输、设备处理和操作系统调度。超时、串口异常或设备错误状态会停止示例、输出错误并返回退出码 2，不把旧值伪装成新采样。

`host_rx_unix_s` 是主机接收并解码时的 Unix 秒，`host_rx_monotonic_s` 用来计算本机间隔；两者都不是硬件 ADC 采样时间。角度转换为 rad，直线转换为 m。`calibration_valid_flag` 直接反映校准有效位；`measurement_warnings` 明确列出弱磁、校准中、未校准或越界，保留这些原始样本供观察，不把它们认定为控制可用。成功解包不等于测量正确。这个示例没有运动控制、ROS 2 节点、校准命令或产品级可靠性验证。

读取路径检查返回的类型、模式、波特率、周期、校准位一致性，以及当前固件的角度与 12 位 ADC 格式。未知状态位或不符合格式的数据会停止读取。直线数值不在主机端裁剪到 ±15 mm，因为固件在内部估计限幅后还会减机械零点。解析器在不完整帧后连续 20 ms 没有新字节时重新寻找后续帧，支持截断帧后的恢复；这不替代整体事务超时。

运行无需硬件的协议检查：

```powershell
python -m unittest discover -s tests -v
```

检查覆盖标准 CRC 向量、已核对请求帧、任意字节边界拆包与粘包、CRC/截断帧恢复、长度限制、有符号直线值、两种模式的单位换算、错误状态、配置格式、短写与事务匹配。它们验证软件行为，未替代板级、电磁兼容或机器人闭环验证。

原工程另有带图形界面的 [上位机](../../wiki/Host-Tools.md)，放在 `software/host/`；本目录的示例不依赖 PySide6、PyQtGraph 或 NumPy。