OSSM WebSocket 控制 MCP 服务器

通过二进制 WebSocket 命令控制OSSM设备的模型上下文协议（MCP）服务器。此工具使AI能够以精确的时间控制OSSM运动模式。

功能

• 平滑点对点移动，具有可定制的缓动曲线
• 连续循环模式，具有独立的推拉笔划特征
• 局部振动模式，具有可调频率和波形
• 全局速度和加速度限制，确保安全
• 动态范围控制，用于运动边界
• 紧急暂停功能，来自多个控制源

MCP 服务器设置

要求

• 具有兼容固件的OSSM设备
• 在8081端口运行的Godot WebSocket桥接应用程序
• 兼容MCP的AI

1. 在ossm-mcp-server目录中安装依赖项：

npm install

2. 添加到MCP配置（例如：claude_desktop_config.json）：

{
  "mcpServers": {
    "ossm-websocket-control": {
      "command": "node",
      "args": ["/绝对路径/to/ossm-mcp-server.js"]
    }
  }
}

3. 重启AI桌面应用程序以加载新的MCP服务器

可用函数

ossm_smooth_move

执行带有缓动曲线的平滑点对点移动。

参数：

• durationMs（必需）：移动持续时间（毫秒）
• position（必需）：目标位置（0-10000，其中10000=全长）
• transition：过渡类型 - LINEAR, SINE, CIRC, EXPO, QUAD, CUBIC, QUART, QUINT（默认：SINE）
• ease：缓动类型 - EASE_IN, EASE_OUT, EASE_IN_OUT, EASE_OUT_IN（默认：EASE_IN_OUT）
• aux：辅助功能位掩码（默认：0）

示例：

// 平滑2秒移动到75%位置，使用正弦过渡
ossm_smooth_move(2000,  7500, "SINE", "EASE_IN_OUT", 0)

ossm_loop

定义连续来回运动模式。

参数：

• pushStroke（必需）：定义前进运动的对象
  • durationMs：持续时间（毫秒）
  • transition：过渡类型（必需）
  • ease：缓动类型（必需）
  • aux：辅助功能（默认：0）
• pullStroke（必需）：定义返回运动的对象（与pushStroke相同结构）

重要： 循环运动范围由全局范围限制控制（参见ossm_set_range_limit），而不是位置参数。

示例：

// 快速循环，每个笔划有不同的特性
ossm_loop(
  {durationMs: 800, transition: "SINE", ease: "EASE_IN", aux: 0},
  {durationMs: 1200, transition: "CIRC", ease: "EASE_OUT", aux: 0}
)

ossm_vibrate

配置具有可调波形的局部振动模式。

参数：

• durationMs（必需）：持续时间（毫秒）（-1表示无限，0表示停止）
• halfPeriodMs（必需）：半周期（毫秒）（控制频率，最小值：10毫秒）
• position（必需）：振动中心位置（0-10000）
• range（必需）：行程范围百分比（0-20%）
• smooth：波形平滑度（100=三角波，200=方波，默认：112）

安全指南：

• 高频+小范围：使用10-50毫秒的半周期与2-10%的范围，产生强烈的局部振动
• 低频+大范围：使用50-200毫秒的半周期与10-20%的范围，产生明显的振荡
• 避免：大范围（>10%）与极高频率（<20毫秒）组合，可能会使硬件承受压力

示例：

// 中心位置的轻柔25Hz振动
ossm_vibrate(-1, 20, 5000, 5, 112)

ossm_pause

立即暂停所有当前运动。作为从任何控制源的紧急停止工作。

参数： 无

ossm_set_speed_limit

设置所有运动模式下的全局电机速度限制。

参数：

• speedHz（必需）：最大速度（步数/秒）

ossm_set_acceleration

设置所有运动模式下的全局电机加速度限制。

参数：

• accel（必需）：最大加速度（步数/秒²）

ossm_set_range_limit

设置位置控制的运动范围边界。

参数：

• range（必需）：要设置的限制 - "MIN_RANGE" 或 "MAX_RANGE"
• limit（必需）：位置限制（0-10000）

注意： 范围限制会自动影响循环命令，但需要重新发送振动命令才能生效。

重要行为差异

循环命令

• 自动更新：随着全局设置更改（范围限制、速度限制）自动更新
• 运动边界由全局范围限制控制
• 适用于全轨模式和序列

振动命令

• 手动更新：在更改全局设置后必须重新发送命令
• 自包含的位置和范围参数
• 适用于局部效果和高频模式

安全指南

紧急控制

• 暂停命令：从MCP或设备UI立即生效
• 模式切换：在不同运动类型之间平滑过渡
• UI覆盖：设备界面可以随时停止MCP发起的运动

参数限制

• 振动频率：测试安全上限为50Hz（20毫秒半周期），更高频率可能导致跳步
• 范围边界：系统自动将运动约束在物理轨道范围内
• 速度限制：全局限制防止所有模式下电机过度应力

最佳实践

1. 逐步测试：从保守设置开始并调整
2. 监控电机行为：观察跳步、过热或应变
3. 使用适当的组合：高频与小范围，低频与大范围
4. 紧急停止准备：始终知道如何快速暂停运动