这是一个基于 Gemini Vision AI 的 PAROL6 机械臂智能控制系统，能够通过自然语言和视觉识别实现机器人的自动化操作。该系统将传统的 GUI 控制方式转变为可编程的研究级平台，支持视觉引导操作和自然语言控制。
- ✅ 自然语言控制：支持文本和语音输入
- ✅ 视觉识别：集成 Intel RealSense D435I 深度相机
- ✅ AI 驱动：使用 Google Gemini 2.5 Flash 视觉模型
- ✅ 精确控制：毫米级定位精度
- ✅ 远程操作：UDP 客户端-服务器架构
- ✅ 安全保护：多层安全检查和急停监控
┌─────────────────────────────────────────────────────────────┐
│ 用户交互层 (顶层) │
│ - 自然语言输入（文本/语音） │
│ - Gemini AI 理解和规划 │
└─────────────────────┬───────────────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────────────┐
│ 视觉处理层 (中层) │
│ - RealSense 深度相机 │
│ - 物体检测和3D定位 │
│ - 手眼标定 │
└─────────────────────┬───────────────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────────────┐
│ 机器人控制层 (底层) │
│ - UDP 服务器（headless_commander.py） │
│ - 运动学计算和轨迹规划 │
│ - 串口通信和实时控制 (100Hz) │
└─────────────────────────────────────────────────────────────┘
PAROL6-Python-API-Gemini-Vision-Public/
├── Headless/
│ ├── headless_commander.py # 机器人控制服务器
│ ├── robot_api.py # 客户端 API（30+ 控制函数）
│ ├── smooth_motion.py # 平滑轨迹生成
│ ├── PAROL6_ROBOT.py # 机器人参数配置
│ ├── Gemini/
│ │ ├── gemini.py # Gemini AI 控制器
│ │ ├── robot_vision_tools.py # 视觉工具函数
│ │ ├── bounding_box_model.py # 物体检测模型
│ │ └── supplementary_functions.py # 辅助功能
│ └── Vision/
│ ├── vision_controller.py # 视觉处理控制器
│ ├── calibrate_hand_eye.py # 手眼标定
│ └── validate_calibration.py # 标定验证
├── README.md # 英文项目说明
├── API-Specific-README.md # API 详细文档
└── 中文使用说明.md # 本文档
| 输入类型 | 说明 | 示例 |
|---|---|---|
| 自然语言命令 | 文本或语音描述任务 | "请抓取红色的方块并放到蓝色盒子里" |
| 视觉数据 | RealSense D435I 深度相机 | RGB-D 图像流（640×480 @ 30fps） |
| API 调用 | Python 函数直接控制 | move_robot_joints([90, -45, 90, 0, 45, 180]) |
| 关节角度 | 6个关节的角度值（度） | [0, -90, 180, 0, 0, 180] |
| 笛卡尔坐标 | 位置和姿态 (mm 和度) | [250, 0, 200, 180, 0, 90] |
| 输出类型 | 说明 | 精度 |
|---|---|---|
| 关节运动 | 6轴协调运动 | ±0.1° |
| 笛卡尔运动 | 直线/曲线路径 | ±1mm |
| 夹爪控制 | 开合和力控制 | 0-255 级位置 |
| 状态反馈 | 位置、速度、IO状态 | 实时更新 |
| 视觉信息 | 物体3D位置和方向 | 毫米级精度 |
| 语音/文本反馈 | AI 响应和状态报告 | 自然语言 |
- 关节运动 (
move_robot_joints): 控制6个关节到指定角度 - 位置运动 (
move_robot_pose): 移动到笛卡尔坐标位置 - 笛卡尔直线 (
move_robot_cartesian): 保证直线路径运动 - 点动控制 (
jog_robot_joint,jog_cartesian): 手动微调位置
- 圆形轨迹 (
smooth_circle): 在指定平面画圆 - 圆弧运动 (
smooth_arc_center,smooth_arc_parametric): 精确圆弧路径 - 样条曲线 (
smooth_spline): 通过多个路点的平滑曲线 - 螺旋运动 (
smooth_helix): 螺旋式运动路径 - 混合运动 (
smooth_blend): 多段运动平滑衔接
- 物体检测: 使用 Gemini Vision AI 识别物体
- 3D 定位: 深度相机获取物体空间坐标
- 智能抓取: 自动规划抓取姿态和路径
- 精确放置: 视觉引导的放置操作
- 手眼标定: ChArUco 标定板标定系统
- 电动夹爪: 位置、速度、力控制 (0-255)
- 气动夹爪: 开/合控制（数字输出端口）
- 物体检测: 夹爪状态反馈
- 文本模式: 逐步文本命令控制
- 语音模式: 按住空格键语音输入
- 自主模式: AI 自动分解复杂任务
- 组合功能: 多步骤操作自动执行
# 核心依赖
pip3 install roboticstoolbox-python==1.0.3
pip3 install numpy==1.23.4
pip3 install scipy==1.11.4
pip3 install spatialmath
# 串口和计时
pip3 install pyserial
pip3 install oclock
pip3 install keyboard
# 视觉处理
pip3 install pyrealsense2
pip3 install opencv-python
# Gemini AI
pip3 install google-genai
pip3 install python-dotenv
# 音频处理（可选，用于语音输入）
pip3 install pyaudio# 仅需要标准库，如果需要姿态矩阵功能：
pip3 install numpy==1.23.4
pip3 install spatialmath在项目根目录创建 .env 文件：
GEMINI_API_KEY=你的_Gemini_API_密钥获取 API 密钥: https://makersuite.google.com/app/apikey
cd Headless
python headless_commander.py等待提示：✓ Robot ready 和 Listening for commands on port 5001
文本模式（推荐新手）:
cd Headless/Gemini
python gemini.py --mode text自主模式（复杂任务）:
python gemini.py --mode autonomous语音输入模式:
python gemini.py --mode text --input audio文本模式下的命令示例：
你: 请向前移动 50mm
AI: [执行移动并确认]
你: 抓取红色的方块
AI: [检测物体 → 规划路径 → 抓取]
你: 把它放到蓝色盒子里
AI: [移动到目标 → 放置 → 松开]
自主模式下的复杂任务：
你: 清理桌面上所有的红色物体，把它们放到绿色容器里
AI: [自动执行]
1. 扫描检测所有红色物体
2. 逐个抓取
3. 放置到容器
4. 返回检测更多物体
5. 完成并报告
创建控制脚本 my_control.py:
from Headless.robot_api import *
# 1. 机器人回零
home_robot()
# 2. 移动到指定关节角度（5.5秒完成）
move_robot_joints([90, -45, 90, 0, 45, 180], duration=5.5)
# 3. 移动到笛卡尔坐标（位置：x,y,z 姿态：Rx,Ry,Rz）
move_robot_pose([250, 0, 200, 180, 0, 90], speed_percentage=50)
# 4. 直线运动到目标点
move_robot_cartesian([200, -50, 180, 180, 0, 135], duration=4.0)
# 5. 画圆（中心点，半径，平面，时间）
smooth_circle(center=[200, 0, 200], radius=50, plane='XY', duration=5.0)
# 6. 控制夹爪
control_electric_gripper(action='open')
control_electric_gripper(action='move', position=200, speed=150)
# 7. 查询状态
pose = get_robot_pose()
print(f"当前位置: {pose}")
angles = get_robot_joint_angles()
print(f"当前关节角度: {angles}")
# 8. 执行轨迹
trajectory = [
[200, 0, 200, 0, 0, 0],
[250, 50, 200, 0, 0, 45],
[200, 100, 200, 0, 0, 90]
]
execute_trajectory(trajectory, timing_mode='duration',
timing_value=10.0, motion_type='spline')运行：
python my_control.py使用视觉工具进行智能抓取：
from Headless.Gemini.robot_vision_tools import RobotVisionTools
from Headless.Vision.vision_controller import VisionController
# 初始化视觉系统
vision = VisionController()
vision.start()
robot_vision = RobotVisionTools(vision)
# 智能抓取流程
result = robot_vision.pick_object(
object_description="红色的立方体",
approach_style="vertical" # 垂直抓取
)
if result['success']:
# 放置到指定位置
robot_vision.place_at_position(
target_position=[300, 100, 50], # 目标位置
approach_height=50 # 接近高度
)move_robot_joints(
joint_angles=[90, -45, 90, 0, 45, 180], # 6个关节角度（度）
duration=5.0, # 运动时间（秒）
# 或者使用速度控制：
# speed_percentage=75, # 速度百分比 (0-100)
wait_for_ack=True, # 等待完成确认
timeout=10.0 # 超时时间
)move_robot_pose(
pose=[250, 0, 200, 180, 0, 90], # [x, y, z, Rx, Ry, Rz]
speed_percentage=50, # 速度百分比
wait_for_ack=True
)move_robot_cartesian(
pose=[200, -50, 180, 180, 0, 135],
duration=4.0
)# 单关节点动
jog_robot_joint(
joint_index=0, # 关节索引 (0-5正向, 6-11负向)
speed_percentage=40,
duration=2.0 # 时间
# 或者：distance_deg=15 # 角度
)
# 多关节同时点动
jog_multiple_joints(
joints=[0, 3, 5], # 关节列表
speeds=[70, 40, 60], # 对应速度
duration=1.2
)
# 笛卡尔点动
jog_cartesian(
frame='TRF', # 'TRF'工具坐标系 或 'WRF'世界坐标系
axis='Z+', # 'X+', 'X-', 'Y+', 'Y-', 'Z+', 'Z-'
speed_percentage=50,
duration=1.5
)smooth_circle(
center=[200, 0, 200], # 圆心坐标 (mm)
radius=50, # 半径 (mm)
plane='XY', # 平面: 'XY', 'XZ', 'YZ'
duration=5.0,
clockwise=False # 顺时针/逆时针
)smooth_arc_center(
end_pose=[250, 50, 200, 0, 0, 90], # 终点姿态
center=[200, 0, 200], # 圆弧中心
duration=3.0
)smooth_arc_parametric(
end_pose=[250, 50, 200, 0, 0, 90],
radius=50, # 半径 (mm)
arc_angle=90, # 圆弧角度 (度)
duration=3.0
)waypoints = [
[200, 0, 100, 0, 0, 0],
[250, 50, 150, 0, 15, 45],
[200, 100, 200, 0, 30, 90]
]
smooth_spline(waypoints, duration=8.0)smooth_helix(
center=[200, 0, 150], # 螺旋中心
radius=30, # 半径
pitch=20, # 螺距（每圈高度）
height=100, # 总高度
duration=10.0
)segments = [
{'type': 'LINE', 'end': [250, 0, 200, 0, 0, 0], 'duration': 2.0},
{'type': 'CIRCLE', 'center': [250, 0, 200], 'radius': 50,
'plane': 'XY', 'duration': 4.0},
{'type': 'LINE', 'end': [200, 0, 200, 0, 0, 0], 'duration': 2.0}
]
smooth_blend(segments, blend_time=0.5, duration=10.0)# 校准夹爪
control_electric_gripper(action='calibrate')
# 移动到指定位置
control_electric_gripper(
action='move',
position=200, # 位置 (0-255)
speed=150, # 速度 (0-255)
current=500 # 最大电流 (100-1000 mA)
)
# 查询夹爪状态
status = get_electric_gripper_status(verbose=True)
# 返回: [ID, Position, Speed, Current, StatusByte, ObjectDetected]# 打开夹爪
control_pneumatic_gripper(action='open', port=1)
# 关闭夹爪
control_pneumatic_gripper(action='close', port=1)# 获取当前位置姿态
pose = get_robot_pose() # 返回 [x, y, z, Rx, Ry, Rz]
# 获取当前关节角度
angles = get_robot_joint_angles() # 返回 6个角度值
# 获取关节速度
speeds = get_robot_joint_speeds() # 步/秒
# 获取 IO 状态
io_status = get_robot_io(verbose=True)
# 返回: [IN1, IN2, OUT1, OUT2, ESTOP]
# 检查是否停止
is_stopped = is_robot_stopped(threshold_speed=2.0)
# 检查急停状态
estop = is_estop_pressed()
# 获取完整状态
status = get_robot_status()
# 包含: pose, angles, speeds, IO, gripper, stopped, estop# 延时
delay_robot(2.5) # 延时 2.5 秒
# 停止运动
stop_robot_movement() # 立即停止并清空命令队列
# 回零
home_robot()
# 等待停止
wait_for_robot_stopped(timeout=10.0, poll_rate=0.1)
# 带重试的安全移动
safe_move_with_retry(
move_robot_joints,
[90, -45, 90, 0, 45, 180],
duration=5.0,
max_retries=3,
retry_delay=1.0
)from Headless.robot_api import *
# 1. 初始化
home_robot()
# 2. 移动到观察位置
move_robot_joints([0, -90, 180, 0, -45, 180], duration=3.0)
# 3. 打开夹爪
control_electric_gripper(action='open')
# 4. 移动到抓取位置
move_robot_cartesian([200, 0, 100, 180, 0, 0], duration=2.0)
# 5. 关闭夹爪抓取
control_electric_gripper(action='move', position=200, speed=100, current=500)
delay_robot(1.0)
# 6. 抬起
move_robot_cartesian([200, 0, 200, 180, 0, 0], duration=2.0)
# 7. 移动到放置位置
move_robot_cartesian([300, 100, 200, 180, 0, 0], duration=3.0)
# 8. 下降
move_robot_cartesian([300, 100, 110, 180, 0, 0], duration=2.0)
# 9. 松开
control_electric_gripper(action='open')
# 10. 返回安全位置
home_robot()from Headless.Gemini.robot_vision_tools import RobotVisionTools
from Headless.Vision.vision_controller import VisionController
# 初始化
vision = VisionController()
vision.start()
robot_vision = RobotVisionTools(vision)
# 执行抓取序列
objects_to_pick = ["红色方块", "蓝色圆柱", "绿色三角形"]
for obj_name in objects_to_pick:
# 检测并抓取
result = robot_vision.pick_object(
object_description=obj_name,
approach_style="vertical"
)
if result['success']:
print(f"成功抓取 {obj_name}")
# 放置到分类区域
robot_vision.place_at_position(
target_position=[300, 150, 50],
approach_height=50
)
print(f"{obj_name} 已放置")
else:
print(f"抓取 {obj_name} 失败: {result['message']}")
vision.stop()from Headless.robot_api import *
# 绘制正方形
def draw_square(center, size, height, duration):
half_size = size / 2
corners = [
[center[0] + half_size, center[1] + half_size, height, 0, 0, 0],
[center[0] - half_size, center[1] + half_size, height, 0, 0, 0],
[center[0] - half_size, center[1] - half_size, height, 0, 0, 0],
[center[0] + half_size, center[1] - half_size, height, 0, 0, 0],
[center[0] + half_size, center[1] + half_size, height, 0, 0, 0]
]
execute_trajectory(corners, timing_mode='duration',
timing_value=duration, motion_type='linear')
# 绘制圆形
def draw_circle(center, radius, height, duration):
smooth_circle(center=[center[0], center[1], height],
radius=radius,
plane='XY',
duration=duration)
# 执行
home_robot()
draw_square(center=[200, 0], size=80, height=150, duration=8.0)
delay_robot(1.0)
draw_circle(center=[200, 0], radius=40, height=150, duration=5.0)from Headless.robot_api import *
def pick_and_stack(objects_positions, stack_position, stack_height_increment=30):
"""
从多个位置拾取物体并堆叠
"""
current_stack_height = 50 # 初始高度
for i, obj_pos in enumerate(objects_positions):
print(f"拾取物体 {i+1}/{len(objects_positions)}")
# 打开夹爪
control_electric_gripper(action='open')
# 移动到物体上方
approach_pos = obj_pos.copy()
approach_pos[2] += 100
move_robot_cartesian(approach_pos, duration=2.0)
# 下降抓取
move_robot_cartesian(obj_pos, duration=1.5)
control_electric_gripper(action='move', position=200, speed=80)
delay_robot(1.0)
# 抬起
move_robot_cartesian(approach_pos, duration=1.5)
# 移动到堆叠位置上方
stack_approach = stack_position.copy()
stack_approach[2] = current_stack_height + 100
move_robot_cartesian(stack_approach, duration=3.0)
# 下降放置
place_pos = stack_position.copy()
place_pos[2] = current_stack_height
move_robot_cartesian(place_pos, duration=1.5)
# 松开
control_electric_gripper(action='open')
delay_robot(0.5)
# 抬起
move_robot_cartesian(stack_approach, duration=1.5)
# 更新堆叠高度
current_stack_height += stack_height_increment
print("堆叠完成！")
# 使用示例
objects = [
[200, 100, 50, 180, 0, 0],
[200, -100, 50, 180, 0, 0],
[250, 0, 50, 180, 0, 0]
]
stack_location = [150, 0, 50, 180, 0, 0]
home_robot()
pick_and_stack(objects, stack_location, stack_height_increment=25)
home_robot()视觉引导操作需要先进行手眼标定，将相机坐标系与机器人坐标系对齐。
cd Headless/Vision
python generate_charuco_board.py打印生成的 ChArUco 标定板（A4 纸）
python calibrate_hand_eye.py按照提示：
- 将标定板放在相机视野内
- 机器人自动移动到多个位置采集数据
- 自动计算手眼变换矩阵
- 保存标定结果到
Results/calibration/目录
python validate_calibration.py检查标定精度，应该达到 ±3mm 以内
python calibration_refinement.py通过迭代优化提高精度
如果客户端和服务器不在同一台电脑：
编辑 Headless/robot_api.py:
SERVER_IP = "192.168.1.100" # 改为服务器 IP
SERVER_PORT = 5001 # 默认端口确保防火墙允许 UDP 5001 和 5002 端口
编辑 Headless/Vision/vision_controller.py:
CAMERA_WIDTH = 640
CAMERA_HEIGHT = 480
CAMERA_FPS = 30编辑 Headless/Gemini/robot_vision_tools.py:
APPROACH_HEIGHT = 50 # 接近高度 (mm)
GRASP_HEIGHT = 100 # 抓取后抬升高度 (mm)
SPEED_APPROACH = 40 # 接近速度 (%)
SPEED_GRASP = 20 # 抓取速度 (%)⚠️ 急停按钮: 确保急停按钮随时可触及⚠️ 工作空间: 保持工作区域无障碍物⚠️ 电源: 使用稳定的电源供应⚠️ 固定: 确保机器人底座固定牢固
- ✓ 系统自动检查关节限位
- ✓ 运动前验证逆运动学解
- ✓ 速度同步防止超速
- ✓ 急停触发立即停止所有运动
- ✓ 命令队列自动清空
- 首次使用先在低速度测试
- 确认工作空间范围
- 观察首次运动路径
- 保持监控运行状态
- 异常情况立即按急停
现象: Serial port not found
解决:
- Windows: 检查设备管理器中的 COM 端口号
- Linux: 检查
/dev/ttyUSB*或/dev/ttyACM* - 更新
com_port.txt文件中的端口号 - 检查串口权限:
sudo usermod -a -G dialout $USER
现象: 命令无响应
解决:
- 检查服务器是否启动
- 确认 IP 地址和端口正确
- 检查防火墙设置
- 测试网络连通性:
ping 服务器IP
现象: IK solution not found
解决:
- 目标位置可能超出工作空间范围
- 检查姿态角度是否合理
- 尝试从当前位置分步移动
- 使用
get_robot_pose()查看可达范围
现象: RealSense camera not found
解决:
- 检查 USB 连接（建议 USB 3.0）
- 更新 RealSense 驱动
- 运行
realsense-viewer测试相机 - 检查相机权限
现象: API key invalid
解决:
- 检查
.env文件中的 API 密钥 - 确认 API 密钥未过期
- 检查网络连接
- 验证 API 配额
现象: 抓取位置偏移
解决:
- 重新进行手眼标定
- 增加标定采样点数量
- 确保标定板打印比例准确
- 使用
validate_calibration.py验证 - 尝试
calibration_refinement.py优化
| 指标 | 数值 |
|---|---|
| 控制频率 | 100 Hz |
| 定位精度 | ±1 mm |
| 重复精度 | ±0.5 mm |
| 最大负载 | 1.2 kg |
| 最大速度 | 100%（关节相关） |
| 工作半径 | 100-400 mm |
| 响应延迟 | <50 ms (局域网) |
| 视觉帧率 | 30 fps |
| Gemini 响应 | 1-3 秒 |
✅ 桌面物体分拣 ✅ 视觉引导装配 ✅ 自动化测试 ✅ 教学演示 ✅ 研究实验 ✅ 原型开发
❌ 高速生产线（速度限制） ❌ 精密微米级加工 ❌ 重载工业应用 ❌ 长时间连续运行（建议<4小时/次）
- PAROL6 官方: https://github.com/PCrnjak/PAROL-commander-software
- Discord 社区: https://discord.com/invite/prjUvjmGpZ
- Gemini API: https://ai.google.dev/gemini-api/docs
- RealSense SDK: https://github.com/IntelRealSense/librealsense
- 问题反馈: 项目 Issues 页面
请参考项目根目录的 LICENSE 文件
- PAROL6 创建者及社区
- Google Gemini AI 团队
- Intel RealSense 团队
- 所有贡献者和测试者
如有问题或建议：
- 提交 GitHub Issue
- 加入 PAROL6 Discord 频道
- 查看详细 API 文档：
API-Specific-README.md
祝使用愉快！🤖