Skip to main content

MyCobot 280 Python API 使用说明

API（Application Programming Interface）又称应用程序编程接口函数，是预先定义好的函数，使用以下函数接口时，请在一开始就导入我们的 API 库，输入如下代码，否则无法运行成功：

## 示例
from pymycobot import MyCobot280

mc = MyCobot280('/dev/ttyAMA0', 1000000)

## 获取所有关节当前的角度
angles = mc.get_angles()
print(angles)

## 将 1 关节移动到 40，速度设置为 20
mc.send_angle(1, 40, 20)

注意： 个别函数接口有返回值，但是直接输入代码，返回的结果是没有返回值的，需要使用 print 函数把结果打印出来。比如，想要获取机械臂当前的角度值可使用 get_angles()，但是直接输入该函数是没有结果的，正确写法是：print(get_angles()) 即可把速度值打印出来。下面对 API 说明部分如果标注无返回值，则不需要使用 print 函数，反之则需使用 print 函数打印结果。

1. 系统状态​

1.1 get_system_version()​

  • 功能: 获取机器主控版本（atom 固件版本）
  • 返回值： 固件版本号

1.2 get_basic_version()​

  • 功能: 获取 M5 版本的 basic 固件版本
  • 返回值： float 固件版本

1.3 get_error_information()​

  • 功能: 获取机器人错误信息
  • 返回值：
    • 0：无错误信息。
    • 1～6：对应关节超出极限位置。
    • 16～19：碰撞保护。
    • 32：运动学逆解无解。
    • 33～34：直线运动无相邻解。

1.4 clear_error_information()​

  • 功能: 清除机器人错误信息

2. 机器人整体运行状态​

2.1 power_on()​

  • 功能: atom 打开通信（默认打开）
  • 返回值: 1 - 上电完成

2.2 power_off()​

  • 功能: 机械臂掉电
  • 返回值: 1 - 掉电完成

2.3 is_power_on()​

  • 功能: 判断机械臂是否上电
  • 返回值:
    • 1: 上电
    • 0: 掉电
    • -1: 错误

2.4 release_all_servos(data=None)​

  • 功能： 放松所有机械臂关节
  • 参数：data（可选）：关节放松方式，默认为阻尼模式，若提供 data 参数可指定为非阻尼模式（1-Undamping）。
  • 返回值： 1 - 释放完成

2.5 focus_servo(servo_id)​

  • 功能: 单个舵机上电
  • 参数: servo_id: int, 1-6
  • 返回值: 1: complete

2.6 is_controller_connected()​

  • 功能: Atom 通信是否连接
  • 返回值:
    • 1: 连接
    • 0: 未连接
    • -1: 错误数据

2.7 read_next_error()​

  • 功能： 机器人错误检测
  • 返回值： list len 6
    • 0: 无异常
    • 1: 通讯断开
    • 2: 通讯不稳定
    • 3: 伺服异常

2.8 get_fresh_mode()​

  • 功能: 查询运动模式
  • 返回值:
    • 0: 插补模式
    • 1: 刷新模式

2.9 set_fresh_mode(mode)​

  • 功能: 设置刷新模式
  • 参数:
    • 1: 总是首先执行最新的命令
    • 0: 以队列的形式按顺序执行指令
  • 返回值: 1: 完成

2.10 set_free_mode(mode)​

  • 功能: 设置自由移动模式
  • 参数:
    • 1: 打开自由移动模式
    • 0: 关闭自由移动模式
  • 返回值: 1: 完成

2.11 is_free_mode()​

  • 功能: 检测是否为自由移动模式
  • 返回值:
    • 1: 自由移动模式
    • 0: 非自由移动模式

2.12 focus_all_servos()​

  • 功能: 所有舵机上电
  • 返回值: 1: complete

2.13 set_vision_mode(mode)​

  • 功能: 设置视觉跟踪模式，限制刷新模式下 send_coords 的姿态翻转。（仅适用于视觉跟踪功能）
  • 参数:
    • 1: 打开
    • 0: 关闭
  • 返回值: 1: 完成

3. MDI 运行与操作​

3.1 get_angles()​

  • 功能： 获取所有关节的度数
  • 返回值： list 所有度数的浮点列表

3.2 send_angle(id, degree, speed)​

  • 功能： 向机械臂发送一个关节度数
  • 参数：
    • id：关节 id，范围 int 1-6
    • degree：度数值（float）
    • speed：机械臂运动速度及范围 1~100
关节 Id范围
1-168 ~ 168
2-140 ~ 140
3-150 ~ 150
4-150 ~ 150
5-155 ~ 160
6-180 ~ 180

注意： 该关节限位信息功能仅在 Atom 固件 ≥ 7.3 且 pymycobot 库 ≥ 4.0.2 时可用。

  • 返回值: 1: 完成

3.3 send_angles(angles, speed)​

  • 功能： 将所有角度发送到机械臂的所有关节
  • 参数：
    • angles：度数列表（List[float]），长度 6
    • speed：（int）1 ~ 100
  • 返回值: 1: 完成

3.4 get_coords()​

  • 功能： 从基于基准的坐标系获取机械臂坐标
  • 返回值： 坐标浮点列表：[x, y, z, rx, ry, rz]

3.5 send_coord(id, coord, speed)​

  • 功能： 向机械臂发送一个坐标
  • 参数：
    • id：向机械臂发送一个坐标，1-6 对应 [x, y, z, rx, ry, rz]
    • coord：坐标值（float）
    • speed：（int）1-100
坐标 ID范围
x-281.45 ~ 281.45
y-281.45 ~ 281.45
z-70 ~ 412.67
rx-180 ~ 180
ry-180 ~ 180
rz-180 ~ 180
  • 返回值: 1: 完成

3.6 send_coords(coords, speed, mode)​

  • 功能： 发送整体坐标和姿态，将机械臂头部从原点移动到您指定的点
  • 参数：
    • coords：坐标列表，值 [x,y,z,rx,ry,rz]，长度 6
    • speed (int)：1 ~ 100
    • mode：(int) 0 - 非线性，1 - 直线运动
  • 返回值: 1: 完成

3.7 pause()​

  • 功能: 控制指令暂停核心并停止所有运动指令
  • 返回值:
    • 1 - 已停止
    • 0 - 没有停止
    • -1 - 错误

3.8 sync_send_angles(angles, speed, timeout=15)​

  • 功能： 同步状态下发送角度，到达目标点后返回
  • 参数：
    • angles：角度值列表（List[float]），长度 6
    • speed：（int）1 ~ 100
    • timeout: 默认 15 秒
  • 返回值： 1：完成

3.9 sync_send_coords(coords, speed, mode=0, timeout=15)​

  • 功能： 同步状态下发送坐标，到达目标点后返回
  • 参数：
    • coords：坐标值列表（List[float]），长度 6
    • speed：（int）1~100
    • mode：（int）0-非线性（默认），1-直线运动
    • timeout: 默认 15 秒
  • 返回值： 1：完成

3.10 get_angles_coords()​

  • 功能： 获取关节角度和坐标
  • 返回值： 一个长度为 12 的列表，前六位为角度信息，后六位为坐标信息

3.11 is_paused()​

  • 功能: 检查程序是否暂停移动命令
  • 返回值:
    • 1 - 已暂停
    • 0 - 没有暂停
    • -1 - 错误

3.12 resume()​

  • 功能: 恢复机器人运动并完成上一个命令
  • 返回值: 1 - 完成

3.13 stop()​

  • 功能: 停止机器人运动
  • 返回值:
    • 1 - 已停止
    • 0 - 没有停止
    • -1 - 错误

3.14 is_in_position(data, flag)​

  • 功能 : 判断是否在某个位置
  • 参数：
    • data：提供一组数据，可以是角度，也可以是坐标值，如果输入角度长度范围是 6，如果输入坐标值长度范围是 6
    • flag（值范围 0 或 1）
      • 0: 角度
      • 1: 坐标
  • 返回值:
    • 1 - 到达
    • 0 - 未到达
    • -1 - 错误

3.15 is_moving()​

  • 功能: 判断机器人是否运动
  • 返回值:
    • 1 运动中
    • 0 未运动
    • -1 错误

3.16 angles_to_coords(angles)​

  • 功能 : 将角度转为坐标
  • 参数：
    • angles：list 所有角度的浮点列表
  • 返回值: list 所有坐标的浮点列表

3.17 solve_inv_kinematics(target_coords, current_angles)​

  • 功能 : 将坐标转为角度
  • 参数：
    • target_coords: list 所有坐标的浮点列表
    • current_angles: list 所有角度的浮点列表，机械臂当前角度
  • 返回值: list 所有角度的浮点列表

4. JOG 运行与操作​

4.1 jog_angle(joint_id, direction, speed)​

  • 功能： 点动控制角度
  • 参数：
    • joint_id：表示机械臂的关节，用关节 ID 表示，范围是 1~6
    • direction (int)：控制机械臂运动的方向，输入 0 为负值运动，输入 1 为正值运动
    • speed：1~100
  • 返回值： 1：完成

4.2 jog_coord(coord_id, direction, speed)​

  • 功能： 点动控制坐标
  • 参数：
    • coord_id: (int) 机械臂坐标范围：1~6
    • direction: (int) 控制机臂运动方向，0 - 负值运动，1 - 正值运动
    • speed: 1 ~ 100
  • 返回值： 1: 完成

4.3 jog_rpy(end_direction, direction, speed)​

  • 功能： 使末端绕基坐标系中固定轴旋转
  • 参数：
    • end_direction: (int) Roll、Pitch、Yaw（1-3）
    • direction: (int) 控制机臂运动方向，1 - 正转，0 - 反转
    • speed: (int) 1 ~ 100
  • 返回值： 1: 完成

4.4 jog_increment_angle(joint_id, increment, speed)​

  • 功能：角度步进，单关节角度增量控制
  • 参数：
    • joint_id：1-6
    • increment：基于当前位置角度的增量移动
    • speed：1~100
  • 返回值： 1: 完成

4.5 jog_increment_coord(id, increment, speed)​

  • 功能：坐标步进，单坐标增量控制
  • 参数：
    • id：坐标轴 1-6
    • increment：基于当前位置坐标的增量移动
    • speed：1~100
  • 返回值： 1: 完成

4.6 set_encoder(joint_id, encoder, speed)​

  • 功能：设置单关节旋转为指定的潜在值
  • 参数
    • joint_id：(int) 1-6
    • encoder：0~4096
    • speed：1~100
  • 返回值： 1：完成

4.7 get_encoder(joint_id)​

  • 功能: 将单关节旋转设置为指定的电位值
  • 参数
    • joint_id: (int) 1-6
  • 返回值: (int) 关节电位值

4.8 set_encoders(encoders, speed)​

  • 功能: 设置机械手六个关节同步执行到指定位置
  • 参数
    • encoder: 0 ~ 4096
    • speed: 1 ~ 100
  • 返回值: 1: 完成

4.9 get_encoders()​

  • 功能：获取机械臂的六个关节电位值
  • 返回值：（list）电位值列表

5. 运行状态及设置​

5.1 get_joint_min_angle(joint_id)​

  • 功能: 获取指定关节的最小运动角度
  • 参数: joint_id : 输入关节 ID（范围 1-6）
  • 返回值： float 角度值

5.2 get_joint_max_angle(joint_id)​

  • 功能: 获取指定关节的最大运动角度
  • 参数: joint_id : 输入关节 ID（范围 1-6）
  • 返回值： float 角度值

5.3 set_joint_min(id, angle)​

  • 功能: 设置最小关节角度限制
  • 参数:
    • id : 输入关节 ID（范围 1-6）
    • angle: 参考 send_angle() 接口中对应关节的限制信息，不得小于最小值
  • 返回值: 1: 完成

5.4 set_joint_max(id, angle)​

  • 功能： 设置最大关节角度限制
  • 参数：
    • id ：输入关节 ID（范围 1-6）
    • angle：参考 send_angle() 接口中对应关节的限制信息，不得大于最大值
  • 返回值： 1：完成

6. 关节电机控制​

6.1 is_servo_enable(servo_id)​

  • 功能: 检测关节连接状态
  • 参数: servo_id 1-6
  • 返回值:
    • 1: 连接成功
    • 0: 未连接
    • -1: 错误

6.2 is_all_servo_enable()​

  • 功能: 检测所有关节连接状态
  • 返回值:
    • 1: 连接成功
    • 0: 未连接
    • -1: 错误

6.3 set_servo_calibration(servo_id)​

  • 功能: 校准指定关节，设置当前位置为角度零点，对应电位值为 2048
  • 参数: servo_id: 1 - 6
  • 返回值: 1: 完成

6.4 release_servo(servo_id)​

  • 功能: 放松指定的单个舵机
  • 参数: servo_id: 1 ~ 6
  • 返回值:
    • 1: 放松成功
    • 0: 放松失败
    • -1: 错误

6.5 focus_servo(servo_id)​

  • 功能: 上电指定舵机
  • 参数: servo_id: 1 ~ 6
  • 返回值:
    • 1: 上电成功
    • 0: 上电失败
    • -1: 错误

6.6 set_servo_data(servo_id, data_id, value, mode=None)​

  • 功能: 设置舵机指定地址的数据参数
  • 参数：
    • servo_id: (int) 关节 id 1 - 6
    • data_id: (int) 数据地址
    • value: (int) 0 - 4096
    • mode: 0 - 表示值为一个字节（默认），1 - 表示值为两个字节
  • 返回值: 1: 完成

6.7 get_servo_data(servo_id, data_id, mode=None)​

  • 功能： 读取舵机指定地址的数据参数
  • 参数：
    • servo_id: (int) 关节 id 1 - 6
    • data_id: (int) 数据地址
    • mode: 0 - 表示值为一个字节（默认），1 - 表示值为两个字节
  • 返回值： 0 ~ 4096

6.8 joint_brake(joint_id)​

  • 功能： 使关节在运动时停止，缓冲距离与现有速度正相关
  • 参数：
    • joint_id: (int) 关节 id 1 - 6
  • 返回值： 1: 完成

7. 9g 舵机​

7.1 move_round()​

  • 功能：驱动 9g 舵机顺时针旋转一圈
  • 返回值： 1: 完成

7.2 set_four_pieces_zero()​

  • 功能：设置四子棋套装电机零位
  • 返回值： 1: 成功, 0: 失败

8. 伺服状态值​

8.1 get_servo_speeds()​

  • 功能：获取所有关节的运动速度
  • 返回值：一个列表

8.2 get_servo_voltages()​

  • 功能：获取关节电压
  • 返回值：一个列表，电压值小于 24V

8.3 get_servo_status()​

  • 功能：获取所有关节的运动状态
  • 返回值：列表 [电压，传感器，温度，电流，角度，过载]，值为 0 表示无错误，值为 1 表示有错误

8.4 get_servo_temps()​

  • 功能：获取关节温度
  • 返回值：一个列表，单位摄氏度

9. 机械臂末端 IO 控制​

9.1 set_color(r, g, b)​

  • 功能: 设置机械臂末端灯光颜色
  • 参数:
    • r (int): 0 ~ 255
    • g (int): 0 ~ 255
    • b (int): 0 ~ 255
  • 返回值： 1: 完成

9.2 set_digital_output(pin_no, pin_signal)​

  • 功能: 设置 IO 状态
  • 参数
    • pin_no (int): 引脚号
    • pin_signal (int): 0 / 1
  • 返回值： 1: 完成

9.3 get_digital_input(pin_no)​

  • 功能: 获取 IO 状态
  • 参数: pin_no (int)
  • 返回值: 0 或 1

9.4 set_pin_mode(pin_no, pin_mode)​

  • 功能: 设置原子中指定引脚的状态模式
  • 参数
    • pin_no (int): 末端引脚号
    • pin_mode (int): 0 - 运行状态, 1 - 停止状态, 2 - 上拉模式
  • 返回值： 1: 完成

10. 机械臂末端夹爪控制​

10.1 set_gripper_state(flag, speed, gripper_type=None, is_torque=None)​

  • 功能: 让夹爪以指定的速度进入到指定的状态
  • 参数:
    • flag (int): 0 - 打开, 1 - 关闭, 254 - 释放
    • speed (int): 0 ~ 100
    • gripper_type (int):
      • 1 : 自适应夹爪 (默认是自适应夹爪)
      • 2 : 五指灵巧手
      • 3 : 平行夹爪
      • 4 : 柔性夹爪
    • is_torque (int)：夹爪是否是力控类型，仅当末端 Atom 固件版本 ≥ 6.5 时才支持该参数
      • 0: 非力控夹爪
      • 1：力控夹爪
  • 返回值： 1: 完成

10.2 set_gripper_value(gripper_value, speed, gripper_type=None, is_torque=None)​

  • 功能: 让夹爪以指定的速度转动到指定的位置
  • 参数:
    • gripper_value (int): 0 ~ 100
    • speed (int): 0 ~ 100
    • gripper_type (int):
      • 1 : 自适应夹爪 (默认是自适应夹爪)
      • 3 : 平行夹爪
      • 4 : 柔性夹爪
    • is_torque (int)：夹爪是否是力控类型，仅当末端 Atom 固件版本 ≥ 6.5 时才支持该参数
      • 0: 非力控夹爪
      • 1：力控夹爪
  • 返回值： 1: 完成

10.3 set_gripper_calibration()​

  • 功能: 将夹爪的当前位置设置为零位
  • 返回值： 1: 完成

10.4 is_gripper_moving()​

  • 功能: 判断夹爪是否正在运行
  • 返回值：
    • 0: 没有运行
    • 1: 正在运行
    • -1: 错误

10.5 get_gripper_value(gripper_type=1)​

  • 功能: 获取夹爪的当前位置数据信息
  • 参数:
    • gripper_type: (int) 默认 1
      • 1: 自适应夹爪
      • 3: 平行夹爪
      • 4: 柔性夹爪
  • 返回值：夹爪的数据信息 (int)

10.6 set_pwm_output(channel, frequency, pin_val)​

  • 功能: PWM 控制
  • 参数:
    • channel : (int): IO 编号
    • frequency: (int): 时钟频率
    • pin_val: (int) 占空比 0 ~ 256；128 表示 50%
  • 返回值： 1: 完成

10.7 set_HTS_gripper_torque(torque)​

  • 功能: 设置自适应夹爪力矩
  • 参数:
    • torque: (int): 150 ~ 980
  • 返回值: 0: 设置失败, 1: 设置成功

10.8 get_HTS_gripper_torque()​

  • 功能: 获取自适应夹爪力矩
  • 返回值: (int) 150 ~ 980

10.9 get_gripper_protect_current()​

  • 功能: 获取夹爪保护电流
  • 返回值: (int) 1 ~ 500

10.10 set_gripper_protect_current(current)​

  • 功能: 设置夹爪保护电流
  • 参数:
    • current: (int): 1 ~ 500
  • 返回值: 1: 完成

10.11 init_gripper()​

  • 功能: 初始化夹爪
  • 返回值: 1: 完成

10.12 gripper_stop()​

注意： 需要 atom 固件版本大于等于 7.3

  • 功能: 停止夹爪运动
  • 返回值： 1: 完成

10.13 is_torque_gripper()​

  • 功能: 判断夹爪是否是力控夹爪类型
  • 返回值：
    • 40: 力控夹爪
    • 9: 非力控夹爪

11. 设置底部 IO 输入/输出状态​

11.1 set_basic_output(pin_no, pin_signal)​

  • 功能：设置底部引脚号的工作状态
  • 参数：
    • pin_no (int) 设备底部标注的编号仅取数字部分
    • pin_signal (int): 0 - 低电平，设置为运行状态, 1 - 高电平，停止状态

11.2 get_basic_input(pin_no)​

  • 功能: 获取底部引脚号的工作状态
  • 参数:
    • pin_no (int) 表示机器人底部的具体引脚号
  • 返回值: 0 - 低电平，运行状态, 1 - 高电平，停止状态

12. TOF​

12.1 get_tof_distance()​

  • 功能: 获取检测到的距离（需要外部距离检测器）
  • 返回值: 检测到的距离值，单位为 mm

13. 通信模式​

13.1 set_transponder_mode(mode)​

  • 功能: 设置串口传输模式
  • 参数:
    • mode : 0 - 关闭透传，1 - 打开透传
  • 返回值: 1: 完成

13.2 get_transponder_mode()​

  • 功能: 获得串口传输的配置信息
  • 返回值: 1: 打开透传，检测所有数据, 0: 关闭透传

14. 坐标变换​

14.1 set_tool_reference(coords)​

  • 功能: 设置工具坐标系
  • 参数：coords: (list) [x, y, z, rx, ry, rz]
  • 返回值: 1: 完成

14.2 get_tool_reference()​

  • 功能: 获取工具坐标系
  • 返回值: (list) [x, y, z, rx, ry, rz]

14.3 set_world_reference(coords)​

  • 功能: 设置世界坐标系
  • 参数：coords: (list) [x, y, z, rx, ry, rz]
  • 返回值: 1: 完成

14.4 get_world_reference()​

  • 功能: 获取世界坐标系
  • 返回值: list [x, y, z, rx, ry, rz]

14.5 set_reference_frame(rftype)​

  • 功能: 设置基坐标系
  • 参数： rftype: 0 - 基坐标（默认） 1 - 世界坐标
  • 返回值: 1: 完成

14.6 get_reference_frame()​

  • 功能: 获取基坐标系
  • 返回值: (list) [x, y, z, rx, ry, rz]

14.7 set_movement_type(move_type)​

  • 功能: 设置移动类型
  • 参数： move_type: 1 - movel, 0 - moveJ
  • 返回值: 1: 完成

14.8 get_movement_type()​

  • 功能: 获取移动类型
  • 返回值: 1 - movel, 0 - moveJ

14.9 set_end_type(end)​

  • 功能: 设置末端坐标系
  • 参数: end (int): 0 - 法兰（默认）, 1 - 工具
  • 返回值: 1: 完成

14.10 get_end_type()​

  • 功能: 获取末端坐标系
  • 返回值: 0 - 法兰（默认）, 1 - 工具

15. 树莓派 -- GPIO​

15.1 gpio_init()​

  • 功能: 初始化 GPIO 模块，设置 BCM 模式
  • 返回值: 1: 完成

15.2 gpio_output(pin, v)​

  • 功能: 设置 GPIO 输出值
  • 参数
    • pin (int) 引脚编号
    • v (int): 0 - 设置为低电平, 1 - 设置为高电平
  • 返回值: 1: 完成

16. utils（模块）​

该模块支持一些帮助方法，使用之前在文件开头输入代码导入模块：

from pymycobot import utils

16.1 utils.get_port_list()​

  • 功能: 获取当前所有串口号列表
  • 返回值: 串口列表 (list)

16.2 utils.detect_port_of_basic()​

  • 功能: 返回第一个检测到的 M5 Basic 的串口号（只会返回一个串口号）
  • 返回值: 返回检测到的端口号，如果没有监测到串口号则返回：None

MyCobot 280 Socket​

注意： raspberryPi 版本 仅支持 python3 使用此类前提的机械臂有服务器，并且已经开启服务。

使用 TCP/IP 控制机械臂

1. 客户端​

## 示例
from pymycobot import MyCobot280Socket

## 默认使用端口 9000
mc = MyCobot280Socket('192.168.10.10', 9000)

res = mc.get_angles()
print(res)

mc.send_angles([0, 0, 0, 0, 0, 0], 20)
## ...

2. 服务端​

服务端文件在 demo 文件夹中，具体请检查 demo 文件夹中的 Server_280.py 文件

3. socket 控制​

注意： 大部分方法与 MyCobot280 类相同，这里只列出新方法。

3.1 set_gpio_mode(mode)​
  • 功能: 设置树莓派 GPIO 针脚模式
  • 参数 mode (str) BCM 或者 BOARD 进入相应模式
3.2 set_gpio_out(pin_no, mode)​
  • 功能: 设置引脚作为输入或者输出
  • 参数
    • pin_no (int) 引脚编号
    • mode (str) in - 输入； out - 输出
3.3 set_gpio_output(pin_no, state)​
  • 功能: 将引脚设置为高、低电平
  • 参数
    • pin_no (int) 引脚编号
    • state (int) 0-设置为低电平, 1-设置为高电平
3.4 get_gpio_in(pin_no)​
  • 功能: 获取引脚电平状态
  • 参数 pin_no (int) 引脚编号
  • 返回值: 0 为低电平, 1 为高电平