支持中心/SDK 与 API 文档

仿真 API

仿真 API 是一个监听在 10001 端口的 WebSocket 连接，负责在应用程序与服务之间传输实时命令和状态循环。

服务器端点

仿真通道是一个监听在 10001 端口的 WebSocket 连接。

端点协议描述
ws://localhost:10001/WebSocket默认本地模拟通道
                // JavaScript 示例
const ws = new WebSocket('ws://localhost:10001')

ws.onopen = () => {
  console.log('Connected to simulation API')
}

消息格式

WebSocket 消息采用 JSON 格式。服务端发送两种类型的消息：初始库存（完整快照）和状态更新（流式更新）。

消息类型：

  • 初始库存：连接时发送一次，包含所有设备的完整配置、状态和运行状况信息
  • 状态更新：每次客户端发送消息时响应，包含 state 和 status，但不包含 config

配置结构

config 对象包含设备的所有配置参数。

                {
  "type": "inverse3",
  "port": "COM12",
  "device_info": { "major_version": 7, "minor_version": 4, "id": "049D", "device_type": 4, "uuid": "…" },
  "extended_device_id": "…",
  "extended_firmware_version": "…",
  "gravity_compensation": { "enabled": true, "scaling_factor": 1.0 },
  "handedness": "right",
  "streaming_mode": "USB",
  "torque_scaling": { "enabled": true },
  "home_return": { "enabled": false },
  "preset": "defaults",
  "basis": { "permutation": "XYZ" },
  "mount": { "position": { "x": 0, "y": 0, "z": 0 }, "rotation": { "w": 1, "x": 0, "y": 0, "z": 0 }, "scale": { "x": 1, "y": 1, "z": 1 } },
  "filters": {
    "force_gate": { "gain": 0.3 },
    "damping": { "scalar": 0.0 }
  }
}

状态结构

state 对象包含设备的实时状态数据。

                {
  "cursor_position": { "x": 0.0, "y": -0.12, "z": 0.15 },
  "cursor_velocity": { "x": 0.0, "y": 0.0, "z": 0.0 },
  "angular_position": { "a0": 0.0, "a1": 0.0, "a2": 0.0 },
  "angular_velocity": { "a0": 0.0, "a1": 0.0, "a2": 0.0 },
  "body_orientation": { "w": 1.0, "x": 0.0, "y": 0.0, "z": 0.0 },
  "current_cursor_force": { "x": 0.0, "y": 0.0, "z": 0.0 },
  "current_cursor_position": { "x": 0.0, "y": 0.0, "z": 0.0 },
  "current_angular_torques": { "a0": 0.0, "a1": 0.0, "a2": 0.0 },
  "current_angular_position": { "a0": 0.0, "a1": 0.0, "a2": 0.0 },
  "control_domain": "cartesian",
  "control_mode": "idle",
  "transform": { "position": { "x": 0, "y": 0, "z": 0 }, "rotation": { "w": 1, "x": 0, "y": 0, "z": 0 }, "scale": { "x": 1, "y": 1, "z": 1 } },
  "transform_velocity": { "position": { "x": 0, "y": 0, "z": 0 }, "rotation": { "w": 1, "x": 0, "y": 0, "z": 0 }, "scale": { "x": 0, "y": 0, "z": 0 } }
}

命令参考

客户端通过 commands 对象发送控制命令。所有键均为可选，服务会静默忽略未知键。

                {
  "session_id": 0,
  "session": {
    "force_render_full_state": {},
    "set_transform": {
      "transform": {
        "position": { "x": 0, "y": 0, "z": 0 },
        "rotation": { "w": 1, "x": 0, "y": 0, "z": 0 },
        "scale": { "x": 1, "y": 1, "z": 1 }
      }
    },
    "configure": {
      "profile": { "name": "myapp", "required_version": "3.5.0" },
      "basis": { "permutation": "ZXY" }
    }
  },
  "inverse3": [
    {
      "device_id": "049D",
      "configure": {
        "preset": { "preset": "device_defaults" },
        "basis": { "permutation": "XYZ" },
        "mount": {
          "transform": {
            "position": { "x": 0, "y": 0, "z": 0 },
            "rotation": { "w": 1, "x": 0, "y": 0, "z": 0 },
            "scale": { "x": 1, "y": 1, "z": 1 }
          }
        },
        "damping": { "scalar": 0.5 },
        "force_gate": { "gain": 0.3 }
      },
      "commands": {
        "set_cursor_force": { "vector": { "x": 0, "y": 0, "z": 0 } },
        "set_cursor_position": { "position": { "x": 0.1, "y": -0.1, "z": 0.15 } },
        "set_angular_torques": { "torques": { "a0": 0, "a1": 0, "a2": 0 } },
        "set_angular_position": { "angles": { "a0": 0, "a1": 0, "a2": 0 } },
        "set_transform": {
          "transform": {
            "position": { "x": 0, "y": 0, "z": 0 },
            "rotation": { "w": 1, "x": 0, "y": 0, "z": 0 },
            "scale": { "x": 1, "y": 1, "z": 1 }
          }
        },
        "probe_position": {}
      }
    }
  ]
}