元驭机器人元驭机器人Hall Lab / 教学 Wiki
查阅资料约 6 分钟阅读Markdown 原文
本页目录 9 个小节

上位机和读取示例

本页对应仓库内 2026-10-27 的上位机及固件快照。原工程后来已有修改，实物操作与录屏请使用互相匹配的固件和上位机。

我们先看一下怎么把数据读到电脑上。观察波形、操作校准，可以用原图形上位机；想先看数据格式和单位，可以用独立命令行示例。这里先读直线位置，然后再换成角度数据。

不接硬件先运行

从仓库根目录执行，建议 Python 3.10 或更新版本：

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

直接执行 python software/examples/read_sensor.py 也会运行直线演示，不连接硬件，不需要第三方包。示例输出每行一个 JSON，含：

  • profile：line 或 encoder。
  • raw_value/raw_unit：协议整数和 0.01_mm 或 0.01_deg。
  • display_value/display_unit：便于人看的 mm 或 deg。
  • si_value/si_unit：便于机器人计算的 m 或 rad。
  • adc_u1_u2_u4、amplitude_adc_counts、flags/flag_names：原码、幅度与状态。
  • calibration_valid_flag、measurement_warnings：校准位，以及弱磁、未校准、校准中和越界提示。异常样本保留供分析，接控制器前需筛选。
  • host_rx_unix_s、host_rx_monotonic_s：主机接收解码时间及本机单调时间。
  • source=simulated_not_hardware：模拟数据标识。

时间字段是主机解码时刻。角度演示使用三相余弦，直线演示使用简化高斯曲线；实际信号还受磁铁、安装、噪声和温度影响，详见测量说明。

源码：独立协议模块 · 只读示例。

用串口读取

准备接实物时，先确认一块板的供电、RS485 接线、USB-RS485 适配器和设备配置，然后执行：

python -m pip install pyserial
python software/examples/read_sensor.py --port COM7 --id 1 --baud 115200 --count 20

将 COM7 换成实际串口。Linux 可替换为 /dev/ttyUSB0。示例先 GET_INFO，再按实际返回的测量类型轮询 GET_DATA；--profile line 只控制演示，不会给真实设备切换模式。固件出厂默认角度，使用直线 PCB 时先按实验步骤切换并校准。

示例默认 20 帧后结束，--count 0 为持续读取；Ctrl+C 停止。--interval-ms 100 表示每次成功读取后等待 100 ms，实际周期还包括请求、应答和调度延迟；所以实际采集率会低于 10 Hz。串口超时、错误应答或拔出导致的异常会结束程序并返回 2，不继续重复最后一个位置。

返回模式、周期、波特率与类型需符合当前协议，信息中的校准有效字节也需与标志一致；12 位 ADC、单圈角度和未知状态位会检查。直线值保留机械零点偏移后的有符号结果，不在主机再次限幅。解析器支持 CRC 错误和截断帧后的恢复，但持续丢包仍会触发事务超时并停止。

示例只发读取命令，不改配置，独立于原 GUI，也不需要 Qt。机器人接口扩展见机器人接入。

启动图形上位机

再看一下图形上位机。保留的原上位机位于 software/host/，依赖文件列出 pyserial、PySide6、pyqtgraph、NumPy，入口为 host/__main__.py。从仓库根目录可按以下方式建立独立环境：

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r software/host/requirements.txt
Set-Location software
..\.venv\Scripts\python.exe -m host

若已在 software 目录且当前环境装好依赖，可直接运行 python -m host。这里提供源码启动方式，尚未连接板卡测试 GUI。

依据：依赖文件，模块入口，GUI 入口，第 931 行。

GUI 演示

  1. 勾选“无设备演示”，设置演示 RPM。
  2. 点击“开始采集”。看三路原码的相位关系，以及角度按 0–360°和连续展开的区别。
  3. 用“开始录制”导出 CSV，再停止录制。

GUI 的无设备演示固定为角度，与之前选的类型无关。直线演示请用前面的命令行示例。

依据：演示模式入口，第 573 行，模拟生成，第 803 行。

接板卡采集

直线板

  1. 刷新串口；初次单板连接通常选 ID 1、115200、类型“不限”，再点连接。
  2. 连接动作会读设备信息；看到“角度编码器”并不代表 PCB 已自动识别。固件默认类型是角度；点击“切换为直线位置”会写入类型并清除原零点和校准。
  3. 先拿开磁铁，点开始校准，保持采集一段时间后点结束校准。这里采的是零磁场基线，不是移动全行程拟合。
  4. 放回磁铁，保持高度与姿态，观察 U1/U2/U4 和位置。敏感宽度默认 8 mm，是模型参数；需要用已知机械位置检查误差并调整。
  5. 把滑台移到选定的机械参考位置，再点“当前位置设为 0 mm”。基线、宽度和机械零点是不同概念。
  6. 先选“主从查询”、间隔 20 ms，开始采集；核对移动方向、弱磁和超出阵列状态。

换成角度板

  1. 换好磁铁与角度 PCB，确认机械结构，再切换为角度编码器。切换会清除两种模式校准和零点。
  2. 保持磁铁安装关系，开始校准并转满至少一圈，再结束校准。
  3. 在明确的机械参考位置设零；观察转动方向和 359°→0°回卷。
  4. 按实际类型改用 deg/rad；同一 angle_cdeg 字段从直线的 0.01 mm 回到角度的 0.01°。

依据：GUI 校准与切换动作，第 601 行，宽度控件，第 437 行，固件切换逻辑，第 902 行。

显示和 CSV

GUI 显示三路 ADC 原码、幅度、位置/角度和差分估算速度；角度速度为 RPM，直线速度为 mm/s。速度由主机收到的相邻位置和时间差估算，并做平滑，不是传感器直接返回的速度。连续角度展开也由主机完成，不能当成掉电保存的多圈编码器。

角度 CSV 表头为 t_s, angle_deg, amplitude, u1, u2, u4, flags, rpm；直线为 t_s, position_mm, amplitude, u1, u2, u4, flags, mm_s。CSV 的 t_s 来源是 Python time.perf_counter()，不是 Unix 时间，也不是从零开始的实验时间；分析时可减第一帧时间求相对秒数。导出的角度保持 0–360°，即使图上显示连续展开角度也一样。

依据：时间与采样解析，第 159 行，速度与展开，第 193 行，CSV 表头，第 627 行，CSV 行，第 785 行。

原 GUI 的几个问题

对照原 GUI 源码，可以看到下面几个问题，接实物时需要留意：

  • 改 ID 后可能报超时，但设备其实已经改成功。 固件应答 SRC 已是新 ID，GUI 事务匹配仍要求旧 ID。只接一台板操作，超时后断开，使用新 ID 重新连接并读信息；若未连上，再检查旧 ID。由非 1 号恢复出厂也会触发同类问题，此时先检查 ID 1/115200。依据：固件设置 ID，第 650 行，GUI 事务匹配，第 372 行。
  • 读取校准时，部分基线/宽度显示会错位。 GET_CAL 布局含 flags，CAL_END 布局不含 flags；GUI _after_cal() 用同一偏移处理两者。不要把错位显示当作硬件基线异常，也不要据此回写宽度。依据：读取校准调用，第 454 行，校准解析，第 526 行，实际协议布局，第 883 行。
  • 主动上报时点“停止采集”不等于让设备停止发送。 stream off 只更改本机状态；后台仍收包，设备的上报模式也会保存在 Flash。需要恢复总线轮询时，选择“主从查询”并开始一次采集，让主机发 SET_MODE=0，再停止。多设备接入前必须检查该配置。依据：采集模式，第 459 行，收包分发，第 410 行。
  • “已连接”首先表示串口已打开。 打开后读信息失败只记录日志，并不自动证明选对了设备。轮询超时也只限频记日志；显示可能保留旧值。机器人必须另外实现超时与新鲜度判断。依据：串口连接，第 339 行，轮询与信息失败，第 421 行。

独立示例只读且遇错停止；校准操作仍需使用原工具或按协议发送命令。

继续阅读：协议字节参考 · 机器人接入和断链处理。