Operations

日常操作指南

适用版本：v0.6.0。硬件采集与控制运行在 Linux 工作站；本机或远程浏览器通过 http://127.0.0.1:8888 使用电机控制、遥操、触觉和视觉。

首次使用先完成安装与配置，远程用户另见Mac／Windows 访问。本页描述操作者流程；复制命令时参照完整 CLI 参数。

1. 启动统一平台

在已激活项目 Python 环境的工作站终端运行：

openarm-runtime platform --profile ~/.config/openarm-runtime/platform.json

已配置的开发仓库也可运行：

cd /path/to/openarm-runtime
python3 run_platform.py

浏览器打开 http://127.0.0.1:8888。平台根据配置启动缺失的服务或复用已运行服务。启动本身不会使能电机、开始跟随或写入零位。

首次替换旧启动方式时，先通过旧服务的原终端 Ctrl+C 或其正常停止方式退出独立服务，再只启动平台。平台会保留外部进程的所有权；它不会代替其他用户停止电机控制器。

状态要看两层

位置	表示什么	不代表什么
平台总览的服务状态	对应页面端口是否可连接	不代表相机在线、电机已失能或反馈新鲜
模块内部状态	实际设备连接、采集错误、反馈与操作结果	不等同于所有机械条件已确认

进入模块后读取内部状态，再执行该模块的操作。服务启动失败时查看对应日志，修复原因后显式重试；平台不会循环自动重启服务。

2. 看视觉与触觉

视觉

选择侧栏“视觉”，查看头部 RGB、深度、左腕和右腕四路画面及各自状态。实机配置须指向存在的设备；画面可打开并不代表四个采集源都正常。

腕部摄像头若共享相同设备序列号，应使用不同且有效的 /dev/v4l/by-path/ 路径，并对照实物确认左右。USB Hub 断连或插口拓扑变化后，旧路径可能失效。先按故障排查确认设备，再更新外部视频配置并正常重启视觉采集。

模拟验证使用独立端口：

openarm-runtime video --simulate --port 5004

打开 http://127.0.0.1:5004。页面上的模拟标记不能当作硬件在线的证据。

触觉

选择“触觉”，在同页查看左臂两个传感器的三维分布、选定测点、XYZ 合力和历史曲线。当前已验证安装中，右臂没有触觉传感器；界面两栏和 --right-device 的名称不改变这个物理归属。

• 轻按并松开对应传感器，确认分布和曲线随实际接触变化。
• “暂停显示”只冻结画面，不停止后台采集。
• 读取错误或过期时，最后一个样本不再是实时数据；修复设备后使用模块“重新连接”。
• 读数单位是原始 counts。合力和 68 点分布来自两次读取，不是同步采样帧；不能直接当成已校准的牛顿值。

两路传感器各有独立采集和视图。平台已转发其嵌套 WebSocket，远程客户端只需 8888 一个 SSH 转发。

3. 电机只读检查

页面正常显示不等于 CAN 配置正常。需要单独检查时，先停止运动操作及冲突的总线读者，再在工作站运行：

ip -details -statistics link show can0
ip -details -statistics link show can1
openarm-runtime --config ~/.config/openarm/classic.json check

这组命令读取链路和电机状态，不修改 CAN 配置。运行时要求健康的 Classic CAN、1 Mbps、FD 关闭、restart-ms 0。出现 DOWN/STOPPED、BUS-OFF 或参数不符时，先定位原因；平台不会自动重配链路。

配置的 left／right 必须与接线一致，确认后才把 mapping_verified 设为 true。示例中的接口名称是示例映射，不能代替实物确认。

4. 手动电机控制

1. 在侧栏打开“电机控制”，检查左右设备反馈。
2. 在面板选择目标“机械臂”，将“操作”设为“手动控制”。
3. 确认工作范围、支撑和设备状态后勾选“机械臂已就绪”。
4. 点击“使能并保持”。此时电机保持使能时捕获的当前位置。
5. 调整该臂关节偏移滑条。界面偏移单位为度，相对于本次使能位置；手动模式范围为 ±30°，速度为 0.1–5°/s。
6. 完成后点击“停止 · 失能”，等待页面报告 8 个电机均已确认失能。

滑条不是绝对零位设置。停止后的失能确认失败会显示错误，应保留报告并检查实际状态，不能仅凭按钮点击认定失能成功。

当前控制会跟踪发起操作的浏览器连接；连接断开会请求停止。但切换平台的“视觉／触觉”页会保留控制页连接，不会停止正在进行的控制。停止操作应明确点击控制页的停止按钮。

5. 主臂标定与遥操

主臂软件标定

在“遥操”页面展开“主臂标定”，选择双臂或单臂：

1. 主臂处于失能状态，自然下垂并保持稳定，点击“① 记录自然零位”。
2. 张开夹爪并保持稳定，点击“② 记录夹爪张开”。
3. 闭合夹爪并保持稳定，点击“③ 记录夹爪闭合”。
4. 点击“④ 保存标定”，确认状态显示已保存。

采集时保持静止约一秒。标定记录的是本地软件参考与夹爪端点，保存在 --calibration 指定的外部 JSON 中，不写主臂舵机寄存器。左右映射及方向需与实物一致。

真实跟随

平台配置的 leader 命令须带 --follow、从臂 --config 和 --report-root。进入遥操页后：

1. 选择“跟随机械臂”：双臂、右臂或左臂。
2. 确认主臂标定完整并保存，主臂反馈新鲜有效且处于失能状态。
3. 检查从臂状态和可运动范围，点击“开始跟随”。
4. 系统完成预检后建立本次接管参考。双臂跟随会协调两侧，任一侧故障会请求停止另一侧。
5. 结束时点击“停止 · 失能”，检查结果和报告。

--follow 只提供这些控件，不会自动开始。单独的电压告警在有效新鲜反馈下按当前项目策略不阻断跟随；其他／组合故障、反馈失效或主臂已使能会被拒绝。

电机控制与遥操之间切换

两个模式共享 CAN，平台将它们作为互斥组。确认切换后，平台先通过正常清理流程停止自己启动的旧模式，再启动新模式；新模式仍需人工开始运动。触觉和视觉可以保持连接。

若旧控制器由平台外部启动，平台会拒绝替它终止进程。由原操作者正常停止后再切换。关闭超时或异常也会阻止切换，平台不会强杀运动进程来抢占 CAN。

6. 从臂硬件零位标定

这与主臂软件标定不同：它会实际移动选中从臂，寻找止挡并写入 8 个电机的硬件零位。仅针对已验证的 OpenArm v2 结构和安装假设；绝对精度、重复性及其他机器尚未完成量化验收。

1. 确认左右映射，卸载负载，清空整个运动范围及线缆，准备失能后的机械支撑。
2. 将选中臂摆到规定参考姿态。
3. 在“电机控制”选择机械臂和“自动标定”。
4. 勾选“姿态已摆好，运动范围已清空”，点击“开始标定”。
5. 等待完整流程及写入验证完成；需要中止时点击“停止 · 失能”。
6. 检查报告、模型对齐及独立读回，不将运动阶段结束当作标定成功。

CLI 是另一入口，执行即开始流程：

openarm-runtime --config ~/.config/openarm/classic.json calibrate \
  --side right --report-root ~/openarm-reports

写入不是原子操作。异常可能出现在部分电机已写入之后，必须根据报告和实际读回处理，不应盲目重试。详见标定步骤与恢复。

7. 日志、报告与退出

默认平台子进程日志位于仓库外的 ~/.local/state/openarm-platform/：

# 在 Linux 工作站另开终端查看；Ctrl+C 只结束 tail
tail -n 100 -F ~/.local/state/openarm-platform/control.log
tail -n 100 -F ~/.local/state/openarm-platform/teleop.log
tail -n 100 -F ~/.local/state/openarm-platform/tactile.log
tail -n 100 -F ~/.local/state/openarm-platform/vision.log

上述每条是独立命令，按需选择一个。平台配置的 log_dir 可覆盖目录。控制、跟随和标定报告位于相应服务 --report-root，包括结束原因及失能验证信息。

正常收工顺序：

1. 在正在操作的模块点击“停止 · 失能”，等待确认。
2. 回到启动平台的工作站终端按 Ctrl+C，等待平台及自己管理的子服务完成关闭。
3. 最后在客户端 SSH 转发终端按 Ctrl+C。

只关闭浏览器、切换页面或断开 SSH 转发，不等于停止整个远端平台。已由外部启动的服务也不会随平台退出而关闭。需要停止后台进程时，先核实进程身份，再向自己的目标 PID 发送 SIGTERM，保留清理和查看报告的机会。

下一步：常用命令 · 故障排查 · Python 集成