跳到主要内容

控制命令

这些是逐 tick、非持久化的命令，通过每个设备的 commands 映射发送。它们只会被应用一次，之后即被丢弃——如果停止发送，设备将返回空闲状态。

除非另有说明，所有控制命令均仅适用于 WebSocket（没有 HTTP 对应的等效命令）。

set_cursor_force​

对光标（末端执行器）施加笛卡尔力。

{
  "inverse3": [{
    "device_id": "049D",
    "commands": {
      "set_cursor_force": {
        "vector": { "x": 0.0, "y": 0.0, "z": 1.5 }
      }
    }
  }]
}
字段类型说明
vectorvec3力，单位为牛顿，位于应用空间中

在同一个 tick 内，力是可叠加的——多个来源（您的应用、SDF HFX、导航）在发送到设备之前会先求和。

set_cursor_position​

将光标指令移动到目标位置（位置模式控制）。

{
  "inverse3": [{
    "device_id": "049D",
    "commands": {
      "set_cursor_position": {
        "position": { "x": 0.0, "y": -0.12, "z": 0.15 }
      }
    }
  }]
}
字段类型说明
positionvec3目标位置，单位为米，位于应用空间中

服务会计算将光标移向目标所需的力。如果启用了 safe-trajectory（安全轨迹），则光标速度将受到速率限制。

set_angular_torques​

对三个关节施加扭矩（角度力模式控制）。

{
  "inverse3": [{
    "device_id": "049D",
    "commands": {
      "set_angular_torques": {
        "torques": { "a0": 0.0, "a1": 0.0, "a2": 0.0 }
      }
    }
  }]
}
字段类型说明
torquesangles3关节扭矩

set_angular_position​

向关节下达目标角度指令（角度位置模式控制）。

{
  "inverse3": [{
    "device_id": "049D",
    "commands": {
      "set_angular_position": {
        "angles": { "a0": 30.0, "a1": 45.0, "a2": 60.0 }
      }
    }
  }]
}
字段类型说明
anglesangles3目标关节角度，单位为度

set_transform​

设置工作区变换（设备空间 → 应用空间）。与其他命令不同，set_transform 是持久性的——服务会记住您最后发送的值。您可以在相机运动期间持续流式发送，也可以只发送一次并保持不变。

{
  "inverse3": [{
    "device_id": "049D",
    "commands": {
      "set_transform": {
        "transform": {
          "position": { "x": 1.0, "y": 0.0, "z": 0.0 },
          "rotation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 },
          "scale":    { "x": 1.0, "y": 1.0, "z": 1.0 }
        }
      }
    }
  }]
}
Verse grip / 无线 verse grip

对于抓握设备（verse grip / 无线 verse grip），仅 rotation 有效。position 和 scale 是为了与 Inverse3 保持架构一致而被接受的，但对抓握设备没有任何效果。

使用导航模块实现自动漂移

如果需要持续移动，请使用导航模块，而不是手动流式发送 set_transform。该模块会为您处理物理计算、触觉反馈以及工作区边界限制。

probe_position / probe_orientation​

仅用于监控的保活命令，适用于不发送控制命令的会话（例如用于观察设备的 Haply Hub 会话）。

{
  "inverse3": [{ "device_id": "049D", "commands": { "probe_position": {} } }]
}
{
  "verse_grip": [{ "device_id": "DEF456", "commands": { "probe_orientation": {} } }]
}
您可能并不需要这些

如果您的会话已在发送任意控制命令（set_cursor_force、 set_cursor_position 等），设备状态会在每次响应时自动刷新。探测命令仅对只读监控会话有用。