chenlin
3ad29356c9
集成通用机器人数值接口、本机控制桥、LeRobot 插件和统一键盘遥操作。采用离线 CoACD 全臂碰撞配方 revision 4、局部装配区切分与结构自接触，限制直接关节位姿写入并保留安全看门狗。同步版本号、变更记录、来源许可证和兼容性验证。
65 lines
3.8 KiB
Markdown
65 lines
3.8 KiB
Markdown
# 本机机器人控制桥接
|
||
|
||
独立于 `training_server` 的实时数值接口。默认监听 `127.0.0.1:8766`；不导入 LeRobot、PyTorch 或训练任务，不执行代码、Shell 或服务器文件路径。
|
||
|
||
## 启动
|
||
|
||
从仓库根目录执行（Python 3.12）：
|
||
|
||
```bash
|
||
source .venv/bin/activate
|
||
python -m pip install -e ./control_bridge
|
||
python -m mujoco_control_bridge
|
||
# 或 npm run control-bridge
|
||
```
|
||
|
||
未设置 `MUJOCO_CONTROL_TOKEN` 时，服务生成至少 256 bit 随机 token，只在启动终端显示一次。也可通过该环境变量提供自己的 token（16–4096 个可打印 ASCII 字符，不含空白）。`--port 0` 自动分配端口，仅测试需要；不能配置非回环监听地址。
|
||
|
||
1. 在本机 HTTP 工作台加载受支持的机器人，显式选择 profile 并通过编译校验。
|
||
2. 在“控制台 → 开源项目 / 外部控制”填写地址和 token，连接桥接。
|
||
3. 播放，然后点击“允许外部控制”。接管会停止 Python/ONNX、锁定 1×并禁止冲突写入。
|
||
4. 在另一终端给 SDK 设置相同 token（不要把 token 放进 URL、源码或命令历史）：
|
||
|
||
```bash
|
||
read -rsp '控制 token: ' MUJOCO_CONTROL_TOKEN; echo
|
||
export MUJOCO_CONTROL_TOKEN
|
||
export MUJOCO_CONTROL_ENDPOINT=http://127.0.0.1:8766
|
||
```
|
||
|
||
## 通用 Python SDK
|
||
|
||
客户端路径仅使用 Python 标准库；HTTP 不使用环境代理，也不跟随重定向。接口不依赖 LeKiwi 的通道名称或数量。
|
||
|
||
```python
|
||
import os
|
||
import time
|
||
from mujoco_control_bridge import SimRobotClient
|
||
|
||
with SimRobotClient(os.environ["MUJOCO_CONTROL_ENDPOINT"]) as robot:
|
||
descriptor = robot.describe()
|
||
values = {
|
||
channel["id"]: min(channel["max"], max(channel["min"], 0.0))
|
||
for channel in descriptor["actionChannels"]
|
||
}
|
||
start = time.monotonic()
|
||
for i in range(90):
|
||
measured = robot.get_observation() # 实际状态，不是目标回显
|
||
accepted = robot.send_action(values) # 物理步后确认，包含已接受的限幅目标
|
||
time.sleep(max(0, start + (i + 1) / 30 - time.monotonic()))
|
||
```
|
||
|
||
通用 SDK 要求提交完整通道集合；部分动作的保持/默认语义由具体插件处理。`robot.reset()` 返回新 `modelEpoch` 的暂停观测，并清除租约；必须在浏览器重新播放、授权，再连接。`is_connected` 不是永久健康承诺：距成功动作超过 500 ms 会在本地失效。
|
||
|
||
## 边界与故障处理
|
||
|
||
- HTTP Bearer token；WS 首帧认证。校验本机 Host/Origin，拒绝查询字符串 token、远程页面和未经认证的预检/连接。
|
||
- 一个浏览器后端、一个 Python 写入者；读取状态不取得写权限。不能自动抢占已有控制者。
|
||
- 64 KiB 帧/请求、每租约至多 100 动作/秒、8 个在途 RPC、一个最新待应用动作；旧目标被替换时返回 `SUPERSEDED`，不会堆积无限队列。
|
||
- 浏览器注册/认证有绝对超时；1 秒 RPC 确认期限、500 ms 动作/观测新鲜度边界。同序号心跳不刷新观测年龄。
|
||
- 暂停、断连、进程崩溃、重载、页面隐藏、冻结超时均撤销授权。轮目标归零、臂/夹爪保持实测姿态，并暂停外控仿真；**不是把所有位置伺服置零**。
|
||
- 回到页面或重新连接不会恢复旧命令。先检查错误、恢复关节限位，再播放/授权。
|
||
- 无 HTTPS/WSS、跨机器访问、锁步、图像流、LeRobot 数据集或训练 API。不要使用端口转发或反向代理扩大此 V1 的信任边界。
|
||
- 浏览器控制 token 仅在页面内存；不写入 `localStorage`/`sessionStorage`、工程导出或应用日志。拥有 token 的本机进程仍被视为可信控制者。
|
||
|
||
测试：`python -m unittest discover -s control_bridge/tests -v`。完整消息结构、错误码和扩展点见 [机器人接口](../docs/robot-interface.md)；LeRobot 用法见 [LeKiwi 示例](../examples/lekiwi/README.md)。
|