v1.3.9

[1.3.9] - 2026-05-14

修复

• 修复 ik(abs=False) 在连续调用时内部增量目标被重置的问题，恢复相对 IK 与绝对 IK 的预期语义差异。
• 保留手动 set_joint / set_joints 对 IK 目标点的同步重置逻辑，避免手动调姿后相对 IK 基于过期目标继续累积。

对齐

• SDK 双臂 IK 模型切换为与 VR 共用的 mantis_2_0_ik.urdf，统一 2.0 / 3.0 的 IK 解算模型语义。
• IK 模型缺失时改为显式报错，不再静默回退到旧版本地模型。

测试

• 新增 tests/test_ik_model_alignment.py，锁定 SDK 与 VR 使用同一份 IK 模型。
• 补充 IK 相对模式目标保持与手动关节控制重置逻辑的回归测试。

v1.3.7

📅 最新版本: V1.3.7 (2026-05-11)

Changelog
格式基于 Keep a Changelog，版本号遵循 语义化版本。

[1.3.7] - 2026-05-11
修复

同步 SDK 关节方向修正表到当前 bridge/runtime 约定，修复 SDK 模式下部分肩部与腕部关节方向与现行 VR/实机表现不一致的问题。
新增 tests/test_joint_direction_map.py 回归测试，锁定 14 个手臂关节的方向映射，避免后续版本回退到旧方向约定。
兼容性

v1.3.7 仅支持机器人端 26.5.11.1 及以上版本。
该版本依赖 2026-05-11 之后的关节方向约定；如果机器人端仍是旧方向定义，请继续使用 v1.3.5。
[1.3.5] - 2026-03-06
新增

新增局域网机器人发现能力（/sn）：
增加 RobotDiscovery 独立发现模块。
支持增量维护在线机器人列表（上线加入、离线超时剔除）。
支持无需实例化的函数接口：
start_robot_discovery()
list_discovered_robots()
stop_robot_discovery()
变更

SDK 连接流程升级为“身份解析 + 状态校验”双重验证：
Mantis.connect 支持按 ip 或 sn 连接。
连接时先通过发现话题解析目标机器人身份，再通过状态话题完成校验。
多机控制隔离增强：
SDK 控制发布改为带 SN 前缀的话题（/sdk/joint_states、/sdk/chassis）。
SDK 状态订阅改为 /sdk/system_status。
避免同一局域网多机器人被同一控制流串控。
文档更新：
更新版本兼容矩阵：
v1.3.2 以下 ↔ < 26.2.3.1
v1.3.2 ~ v1.3.4 ↔ 26.2.3.1 ~ 26.3.3.1
v1.3.5 ↔ 26.3.6.2 ~ < 26.5.11.1
v1.3.6 及以上 ↔ >= 26.5.11.1
工具

新增 test_sn_read.py 诊断脚本，用于直接验证 Zenoh sn 话题是否可读、数据格式是否正确。

v1.3.5

Mantis SDK Release Notes

📅 最新版本: V1.3.5 (2026-03-06)

Changelog

格式基于 Keep a Changelog，版本号遵循 语义化版本。

[1.3.5] - 2026-03-06

新增

• 新增局域网机器人发现能力（/sn）：
  • 增加 RobotDiscovery 独立发现模块。
  • 支持增量维护在线机器人列表（上线加入、离线超时剔除）。
  • 支持无需实例化的函数接口：
    • start_robot_discovery()
    • list_discovered_robots()
    • stop_robot_discovery()

变更

• SDK 连接流程升级为“身份解析 + 状态校验”双重验证：
  • Mantis.connect 支持按 ip 或 sn 连接。
  • 连接时先通过发现话题解析目标机器人身份，再通过状态话题完成校验。
• 多机控制隔离增强：
  • SDK 控制发布改为带 SN 前缀的话题（<SN>/sdk/joint_states、<SN>/sdk/chassis）。
  • SDK 状态订阅改为 <SN>/sdk/system_status。
  • 避免同一局域网多机器人被同一控制流串控。
• 文档更新：
  • 更新版本兼容矩阵：
    • v1.3.2 以下 ↔ < 26.2.3.1
    • v1.3.2 ~ v1.3.4 ↔ 26.2.3.1 ~ 26.3.3.1
    • v1.3.5 及以上 ↔ >= 26.3.6.2

工具

• 新增 test_sn_read.py 诊断脚本，用于直接验证 Zenoh sn 话题是否可读、数据格式是否正确。

问题反馈: GitHub Issues

许可证: MIT License

© 2025-2026 BlueWorm-EAI-Tech. All rights reserved.

v1.3.4

Mantis SDK Release Notes

📅 最新版本: V1.3.4 (2026-02-07)

Changelog

格式基于 Keep a Changelog，版本号遵循 语义化版本。

[1.3.4] - 2026-02-07

修复

• 修复混合使用单关节控制（如 set_shoulder_pitch）与 IK 增量控制时，IK 目标点未更新的问题。

  • 现在所有单关节设置方法 (set_joint, set_shoulder_pitch 等) 都会自动同步 IK 求解器的内部目标状态。
  • 解决了先手动调整关节，再调用 ik(abs=False) 时发生位置回跳的问题。

• 修复 IK 增量控制 (abs=False) 在连续调用时无法正确累积的问题。

• 优化内部目标位姿维护逻辑：

  • set_joints/home 等绝对控制指令会自动同步 IK 目标点。
  • ik(abs=False) 现在基于内部维护的目标点进行累加，确保连续增量运动的连贯性。

• 修复pip下载没有模型文件的问题

问题反馈: GitHub Issues

许可证: MIT License

© 2025-2026 BlueWorm-EAI-Tech. All rights reserved.

v1.3.3

Mantis SDK Release Notes

📅 最新版本: V1.3.3 (2026-02-05)

Changelog

格式基于 Keep a Changelog，版本号遵循 语义化版本。

[1.3.3] - 2026-02-05

修复

• 修复混合使用单关节控制（如 set_shoulder_pitch）与 IK 增量控制时，IK 目标点未更新的问题。

  • 现在所有单关节设置方法 (set_joint, set_shoulder_pitch 等) 都会自动同步 IK 求解器的内部目标状态。
  • 解决了先手动调整关节，再调用 ik(abs=False) 时发生位置回跳的问题。

• 修复 IK 增量控制 (abs=False) 在连续调用时无法正确累积的问题。

• 优化内部目标位姿维护逻辑：

  • set_joints/home 等绝对控制指令会自动同步 IK 目标点。
  • ik(abs=False) 现在基于内部维护的目标点进行累加，确保连续增量运动的连贯性。

问题反馈: GitHub Issues

许可证: MIT License

© 2025-2026 BlueWorm-EAI-Tech. All rights reserved.

v1.3.2

Mantis SDK Release Notes

📅 最新版本: V1.3.2 (2026-02-03)

Changelog

格式基于 Keep a Changelog，版本号遵循 语义化版本。

[1.3.2] - 2026-02-03

文档

• 更新机械臂的运动检测功能，使用上位机实时返回的关节状态作为判断关节运动的依据，避免在运动过程中因为小的误差导致判断错误
• 删除sdk中的平滑滤波，所有的运动规划交给上位机
• 注意！！！：使用本sdk必须将上位机代码、VR程序更新到最新版本，本sdk只适配26.2.3.1以上的机器人代码，请更新sdk后务必升级机器人代码

问题反馈: GitHub Issues

许可证: MIT License

© 2025-2026 BlueWorm-EAI-Tech. All rights reserved.

v1.2.0

Mantis SDK Release Notes

📅 最新版本: V1.2.0 (2026-01-05)

Changelog

格式基于 Keep a Changelog，版本号遵循 语义化版本。

[1.2.0] - 2026-01-05

重构

• 🔧 移除 zenoh-bridge-ros2dds 依赖: 改用纯 Python Zenoh + JSON 格式通讯，解决桥接通讯不稳定问题
• 🔧 删除 CDR 编解码模块: 不再需要 ROS2 消息序列化，代码更简洁
• 🔧 统一 sim/real 模式: SDK 不再区分仿真和实机，统一发布到 sdk/joint_states 和 sdk/chassis 话题

新增

• 🚗 底盘新增 set_friction(linear, angular) 方法，设置摩擦补偿系数
• 🚗 摩擦系数越大，运动时间越长，用于补偿地面摩擦力导致的距离损失

修复

• 🔧 修复夹爪开合方向映射问题（实机 0=打开, 1=关闭，已在 Bridge 端反转）
• 🔧 修复机器人连接时在未建立连接前调用 home() 导致的异常
• 🔧 修复关节方向修正影响 RViz 和实机同步的问题（方向修正移至 Bridge 端）

优化

• 🚀 提高底盘默认线速度: 0.1 m/s → 1.0 m/s
• 🚀 调整底盘默认角速度: 0.5 rad/s → 0.3 rad/s
• 🚀 提高底盘最大速度限制: 线速度 3.0 m/s，角速度 2.0 rad/s

问题反馈: GitHub Issues

许可证: MIT License

© 2025-2026 BlueWorm-EAI-Tech. All rights reserved.

v1.1.0

Mantis SDK Release Notes

📅 最新版本: V1.1.0 (2026-01-04)

Changelog

格式基于 Keep a Changelog，版本号遵循 语义化版本。

[1.1.0] - 2026-01-04

新增

• ⚡ 所有运动方法添加 block 参数，支持阻塞/非阻塞模式
• ⚡ 新增 wait() 方法，等待所有部件运动完成
• ⚡ 新增 is_moving 属性，检查部件是否在运动中
• 🦿 新增 Waist（腰部）控制模块
• 🚗 底盘支持 Gazebo 物理仿真，可在仿真中预览底盘移动
• 🚗 底盘 API 重构为基于距离/角度的安全控制模式

修复

• 🔧 修复双臂 shoulder_yaw 关节零点限位错误（旧: 0.081.04，新: -0.2132.029）
• 🔧 修复夹爪控制时关节位置计算错误导致夹爪移动方向异常的问题
• 🔧 修正夹爪归一化值到实际关节位置的单位转换 (0.0-1.0 → 0.0-0.04m)

问题反馈: GitHub Issues

许可证: MIT License

© 2025-2026 BlueWorm-EAI-Tech. All rights reserved.

v1.0.4

Mantis SDK V1.0.4 Release Notes

📅 2026-1-4

概述

Mantis SDK V1.0 是 Mantis 机器人的 Python 控制接口，无需安装 ROS2，通过 Zenoh 协议直接与机器人通信。适用于客户二次开发、快速原型验证、教学演示等场景。

主要特性

🎮 简洁的 API 设计

from mantis import Mantis

with Mantis(ip="192.168.1.100") as robot:
    robot.left_arm.set_shoulder_pitch(-0.5)
    robot.head.look_left()
    robot.left_gripper.open()

🦾 完整的机器人控制

模块	功能
Arm	双臂 7 自由度控制 (shoulder_pitch/yaw/roll, elbow_pitch, wrist_roll/pitch/yaw)
Gripper	左右夹爪开合控制 (0.0 ~ 1.0)
Head	头部俯仰/偏航控制
Chassis	全向底盘移动控制 (vx, vy, omega)

🛡️ 安全保护

• 关节限位保护: 自动限制在 URDF 定义范围内
• 软停止: stop() 方法立即停止所有运动
• 异常处理: 连接断开自动清理资源

🖥️ 仿真预览

# 仿真模式 - 在 RViz 中预览，不连接实机
with Mantis(sim=True) as robot:
    robot.left_arm.set_joints([0.0, -0.5, 0.0, -1.0, 0.0, 0.5, 0.0])

• 需配合 bw_motion_ws 的 sdk_sim.launch.py 启动
• EMA 平滑算法，运动流畅

📊 关节反馈

def on_feedback(joint_names, positions):
    print(f"关节位置: {dict(zip(joint_names, positions))}")

robot.subscribe_feedback(on_feedback)

API 参考

Mantis 主类

方法	说明
connect()	建立连接
disconnect()	断开连接
home()	所有关节回零位
stop()	停止所有运动
set_smoothing(alpha, rate)	设置仿真平滑参数
subscribe_feedback(callback)	订阅关节反馈

Arm 手臂控制

方法	说明
set_joints(positions)	批量设置 7 个关节
set_joint(index, position)	设置单个关节
set_shoulder_pitch(value)	设置肩部俯仰
set_elbow_pitch(value)	设置肘部俯仰
...	其他关节类似

Gripper 夹爪控制

方法	说明
set_position(value)	设置位置 (0.0 ~ 1.0)
open()	完全张开
close()	完全闭合
half_open()	半开状态

Head 头部控制

方法	说明
set_pose(pitch, yaw)	设置俯仰/偏航
look_left()	看向左边
look_right()	看向右边
look_up()	抬头
look_down()	低头
center()	回中

Chassis 底盘控制

方法	说明
set_velocity(vx, vy, omega)	设置速度
forward(speed)	前进
backward(speed)	后退
strafe_left(speed)	左平移
strafe_right(speed)	右平移
turn_left(speed)	左转
turn_right(speed)	右转
stop()	停止

安装

依赖安装

pip install eclipse-zenoh

SDK 安装

cd mantis
pip install -e .

仿真环境设置

SDK 仿真模式需要配合 ROS2 环境：

# 终端 1: 启动仿真环境
cd ~/bw_motion_ws
source install/setup.bash
ros2 launch bw_sim2real sdk_sim.launch.py

# 终端 2: 启动 Zenoh 桥接
zenoh-bridge-ros2dds -d 99

# 终端 3: 运行 SDK
python your_script.py

注意: 仿真环境由 Mantis Sim2Real 项目提供

系统要求

• Python: 3.8+
• 依赖: eclipse-zenoh
• 仿真模式额外要求: ROS2 Humble + zenoh-bridge-ros2dds

已知限制

• 底盘控制在仿真模式下暂不支持预览
• 仿真模式需要先启动 ROS2 环境和 Zenoh 桥接

---

Changelog

格式基于 Keep a Changelog，版本号遵循 语义化版本。

[1.0.4] - 2026-01-04

修复

• 修复夹爪控制时关节位置计算错误导致夹爪移动方向异常的问题
• 修正夹爪归一化值到实际关节位置的单位转换 (0.0-1.0 → 0.0-0.04m)

[1.0.2] - 2025-12-30

优化代码框架

问题反馈: GitHub Issues

许可证: MIT License

© 2025 BlueWorm-EAI-Tech. All rights reserved.

v1.0.1

Mantis SDK V1.0.1 Release Notes

🎉 首次正式发布 | 📅 2025-12-30

---

概述

Mantis SDK V1.0 是 Mantis 机器人的 Python 控制接口，无需安装 ROS2，通过 Zenoh 协议直接与机器人通信。适用于客户二次开发、快速原型验证、教学演示等场景。

主要特性

🎮 简洁的 API 设计

from mantis import Mantis

with Mantis(ip="192.168.1.100") as robot:
    robot.left_arm.set_shoulder_pitch(-0.5)
    robot.head.look_left()
    robot.left_gripper.open()

🦾 完整的机器人控制

模块	功能
Arm	双臂 7 自由度控制 (shoulder_pitch/yaw/roll, elbow_pitch, wrist_roll/pitch/yaw)
Gripper	左右夹爪开合控制 (0.0 ~ 1.0)
Head	头部俯仰/偏航控制
Chassis	全向底盘移动控制 (vx, vy, omega)

🛡️ 安全保护

• 关节限位保护: 自动限制在 URDF 定义范围内
• 软停止: stop() 方法立即停止所有运动
• 异常处理: 连接断开自动清理资源

🖥️ 仿真预览

# 仿真模式 - 在 RViz 中预览，不连接实机
with Mantis(sim=True) as robot:
    robot.left_arm.set_joints([0.0, -0.5, 0.0, -1.0, 0.0, 0.5, 0.0])

• 需配合 bw_motion_ws 的 sdk_sim.launch.py 启动
• EMA 平滑算法，运动流畅

📊 关节反馈

def on_feedback(joint_names, positions):
    print(f"关节位置: {dict(zip(joint_names, positions))}")

robot.subscribe_feedback(on_feedback)

API 参考

Mantis 主类

方法	说明
connect()	建立连接
disconnect()	断开连接
home()	所有关节回零位
stop()	停止所有运动
set_smoothing(alpha, rate)	设置仿真平滑参数
subscribe_feedback(callback)	订阅关节反馈

Arm 手臂控制

方法	说明
set_joints(positions)	批量设置 7 个关节
set_joint(index, position)	设置单个关节
set_shoulder_pitch(value)	设置肩部俯仰
set_elbow_pitch(value)	设置肘部俯仰
...	其他关节类似

Gripper 夹爪控制

方法	说明
set_position(value)	设置位置 (0.0 ~ 1.0)
open()	完全张开
close()	完全闭合
half_open()	半开状态

Head 头部控制

方法	说明
set_pose(pitch, yaw)	设置俯仰/偏航
look_left()	看向左边
look_right()	看向右边
look_up()	抬头
look_down()	低头
center()	回中

Chassis 底盘控制

方法	说明
set_velocity(vx, vy, omega)	设置速度
forward(speed)	前进
backward(speed)	后退
strafe_left(speed)	左平移
strafe_right(speed)	右平移
turn_left(speed)	左转
turn_right(speed)	右转
stop()	停止

安装

依赖安装

pip install eclipse-zenoh

SDK 安装

cd mantis
pip install -e .

仿真环境设置

SDK 仿真模式需要配合 ROS2 环境：

# 终端 1: 启动仿真环境
cd ~/bw_motion_ws
source install/setup.bash
ros2 launch bw_sim2real sdk_sim.launch.py

# 终端 2: 启动 Zenoh 桥接
zenoh-bridge-ros2dds -d 99

# 终端 3: 运行 SDK
python your_script.py

注意: 仿真环境由 Mantis Sim2Real 项目提供

系统要求

• Python: 3.8+
• 依赖: eclipse-zenoh
• 仿真模式额外要求: ROS2 Humble + zenoh-bridge-ros2dds

已知限制

• 底盘控制在仿真模式下暂不支持预览
• 仿真模式需要先启动 ROS2 环境和 Zenoh 桥接

---

Changelog

格式基于 Keep a Changelog，版本号遵循 语义化版本。

[1.0.1] - 2025-12-30

🎉 首次正式发布

Mantis SDK V1.0 正式版本，提供无 ROS2 依赖的机器人控制接口。

✨ 新增功能

• Mantis 主控制类

  • connect() / disconnect(): 连接管理
  • home(): 所有关节回零位
  • stop(): 停止所有运动
  • set_smoothing(): 设置运动平滑参数
  • subscribe_feedback(): 订阅关节反馈
  • 上下文管理器支持 (with 语句)

• Arm 手臂控制

  • 7 自由度控制 (shoulder_pitch/yaw/roll, elbow_pitch, wrist_roll/pitch/yaw)
  • set_joints(): 批量设置关节
  • set_joint(): 单关节设置
  • set_shoulder_pitch() 等快捷方法
  • 自动关节限位保护

• Gripper 夹爪控制

  • set_position(): 设置位置 (0.0-1.0)
  • open() / close() / half_open(): 预设位置

• Head 头部控制

  • set_pose(): 设置俯仰/偏航
  • look_left() / look_right() / look_up() / look_down(): 快捷方法
  • center(): 回中

• Chassis 底盘控制

  • set_velocity(): 设置速度 (vx, vy, omega)
  • forward() / backward() / strafe_left() / strafe_right(): 移动
  • turn_left() / turn_right(): 转向
  • stop(): 停止

• 仿真预览模式

  • sim=True 参数启用
  • EMA 平滑算法
  • 配合 sdk_bridge_node 在 RViz 显示

• 完整文档

  • Google 风格 docstring
  • pdoc 生成 HTML 文档
  • 中英文注释

---

问题反馈: GitHub Issues

许可证: MIT License

© 2025 BlueWorm-EAI-Tech. All rights reserved.