API说明

API(Application Programming Interface)，即应用程序接口函数，是一些预先定义好的函数。在使用下列函数接口的时候请先在开头导入我们的API库，即输入下方代码，否则无法运行成功：

#适用于myCobot、mechArm系列
from pymycobot.mycobot import MyCobot

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

myCobot / myPalletizer / mechArm / myArm

1 机械臂整体运行状态

1.1 power_on()

• 功能： 机械臂上电
• 返回值： 无

1.2 power_off()

• 功能： 机械臂断电，所有功能将失效
• 返回值： 无

1.3 is power on()

• 功能：判断机械臂是否上电

• 返回值： 1- 机械臂已通电 0 - 机械臂已断电 -1- 错误

1.4 release_all_servos

• 功能： 设置机械臂为自由移动模式(能手动自由摆动机械臂)
• 返回值： 无

1.5 is_controller_connected

• 功能： 判断是否与 Atom 连接
• 返回值： 1- 已连接 0 - 未连接 -1- 错误

1.6 read_next_error()

• 功能： 机械臂错误检测
• 返回值： 0- 无异常 1 - 通讯中断 2 - 通讯不稳定 3 - 舵机异常

1.7 set_fresh_mode(mode)

• 功能：：设置插补/刷新运动模式
• 参数说明： mode: 0：按序执行指令 1: 执行第一个指令
• 返回值： 1- 机械臂已通电 0 - 机械臂已断电 -1- 错误

1.8 get_fresh_mode()

• 功能：：查询插补/刷新运动模式

• 返回值： 0：按序执行指令 1: 执行第一个指令

2 机械臂运行状态和设置

2.1 pause()

• 功能： 让机械臂暂停当前运动
• 返回值： 无

2.2 stop()

• 功能： 让机械臂停止所有运动
• 返回值： 无

2.3 resume()

• 功能： 让机械臂恢复之前所设置的运动
• 返回值： 无

2.4 is_paused()

• 功能： 判断机械臂是否为暂停状态
• 返回值： 1 - 已经暂停 0 - 没有暂停 -1 - 错误

2.5 get_speed()

• 功能： 获取机器人的运动速度
• 返回值： 机器人当前所设定的运行速度，范围在1-100

2.6 set_speed(speed)

• 功能： 设置机器人的运动速度
• 参数说明： speed: 给入你想要设置的速度范围在1-100，单位为mm/s
• 返回值： 无

2.7 get_joint_min_angle(joint_id)

• 功能： 获取指定关节最小能运行到的角度
• 参数说明：joint_id: (int) 您所指定的关节，mycobot系列范围为1~6，mypalletizer系列范围为1-4，myArm系列范围为1-7
• 返回值： angle: 返回来的度数

2.8 get_joint_max_angle(joint_id)

• 功能： 获取指定关节最大能运行到的角度
• 参数说明： joint_id: (int)您所指定的机械臂关节关节，mycobot系列范围为1~6，mypalletizer系列范围为1-4，myArm系列范围为1-7
• 返回值： angle: (float)返回来的度数

2.9 is_servo_enable(servo id)

• 功能： 判断指定关节是否连通
• 参数说明： servo id: 你所指定的关节，mycobot系列范围为1~6，mypalletizer系列范围为1-4，myArm系列范围为1-7
• 返回值： (int) 1 - 连通 0 - 不连通 -1 - 错误

2.10 is_all_servo_enable()

• 功能： 判断机器人的所有关节是否连通
• 返回值： (int) 1 - 连通 0 - 不连通 -1 - 错误

2.11 release_servo(servo_id)

• 功能： 放松指定的关节
• 参数说明： servo id: (int)机械臂的指定关节,mycobot系列范围为1~6，mypalletizer系列范围为1-4，myArm系列范围为1-7
• 返回值： 无

2.12 get_tof_distance()

• 功能： 获取检测到的距离(需要外部距离检测器)
• 返回值： 检测到的距离值，单位为mm。

2.13 get_error_information()

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

2.14 clear_error_information()

• 功能： 清除错误信息

2.15 set_joint_min(id, angle)

• 功能： 设置指定关节最小能运行到的角度
• 参数说明：
  • id: (int)机械臂的指定关节,范围为1~6
  • angle:关节可运行的最小角度
• 返回值： 无

2.16 set_joint_max(id, angle)

• 功能： 设置指定关节最大能运行到的角度
• 参数说明：
  • id: (int)机械臂的指定关节,范围为1~6
  • angle:关节可运行的最大角度
• 返回值： 无

2.17 get_basic_version()

• 功能： 获取固件版本
• 返回值： 固件版本(float)

2.18 set_communicate_mode(mode)

• 功能： 设置basic通讯模式
• 参数说明： (int) 0 - 关闭 1-打开
• 返回值： 无

3 输入程序控制模式(MDI模式)

注意：不同系列的机械臂限位有所不同，可设定姿态数值也有所不同具体可查看对应型号的参数介绍

3.1 get_angles()

• 功能： 获取所有关节角度
• 返回值： list一个浮点值的列表代，表示所有关节的角度

3.2 send_angle(id, degree, speed)

• 功能： 发送指定的单个关节运动至指定的角度
• 参数说明：
  • id: 代表机械臂的关节，六轴有六个关节，四轴有四个关节，有特定的表示方法 关节一的表示法：Angle.J1.value。(也可以用数字1-6来表示)
  • degree: 表示关节的角度
  • speed：表示机械臂运动的速度，范围0~100
• 返回值： 无

3.3 send_angles(degrees, speed)

• 功能： 发送所有角度给机械臂所有关节
• 参数说明：
  • degrees: (List[float])包含所有关节的角度 ,六轴机器人有六个关节所以长度为 6，四轴长度为4，表示方法为：[20,20,20,20,20,20]
  • speed: 表示机械臂运动的速度，取值范围是0-100
• 返回值： 无

3.4 get_coords()

• 功能： 获取当前坐标和姿态
• 返回值： list包含坐标和姿态的列表
  • 六轴：长度为 6，依次为 [x, y, z, rx, ry, rz]
  • 四轴：长度为 6，依次为 [x, y, z, rx]

3.5 send_coord(id,coord,speed)

• 功能： 发送单个坐标值给机械臂进行移动
• 参数说明：
  • id:代表机械臂的坐标，六轴有六个坐标，四轴有四个坐标，有特定的表示方法 X坐标的表示法：Coord.X.value，也有简易的表示方法：如X轴可以填写1,Y填写2,以此类推
  • coord: 输入您想要到达的坐标值
  • speed: 表示机械臂运动的速度，范围是0-100
• 返回值： 无

3.6 send_coords(coords, speed, mode)

• 功能： 发送整体坐标和姿态,让机械臂头部从原来点移动到您指定点
• 参数说明：
  • coords:
    • 六轴：[x,y,z,rx,ry,rz]的坐标值，长度为6
    • 四轴：[x,y,z,rx]的坐标值，长度为4
  • speed: 表示机械臂运动的速度，范围是0-100
  • mode: ( int): 取值限定 0 和 1
    • 0 表示机械臂头部移动的路径为非线性，即随机规划路线，只要机械臂头部以保持规定的姿态移动到指定点即可。
    • 1 表示机械臂头部移动的路径为线性的，即智能规划路线让机械臂头部以直线的方式移动到指定点。
• 返回值： 无

3.7 get_encoders()

• 功能： 获取机械臂所有关节的电位值
• 返回值： list包含机械臂所有关节电位值的列表

3.8 get_encoder(joint_id)

• 功能： 获取机械臂指定的单个关节的电位值
• 参数说明：
  • joint_id: 代表机械臂的关节，六轴机器人有六个关节所以长度为 6，四轴长度为4，有特定的表示方法, 关节一的表示法：Angle.J1.value(也可以用数字1-6来表示)
• 返回值： 您所指定的单个关节电位值

3.9 set_encoder(joint_id, encoder)

• 功能： 发送指定的单个关节运动至指定的电位值
• 参数说明：
  • joint_id: 代表机械臂的关节，六轴机器人有六个关节所以长度为 6，四轴长度为4，有特定的表示方法, 关节一的表示法：Angle.J1.value(也可以用数字1-6来表示)
  • encoder:表示机械臂的电位值，取值范围是 0 ~ 4096
• 返回值： 无

3.10 set_encoders(encoders, sp)

• 功能： 发送电位值给机械臂所有关节
• 参数说明：
  • encoder:表示机械臂的电位值，取值范围是 0 ~ 4096，六轴长度为6，四轴长度为4，表示方法为：[2048,2048,2048,2048,2048,2048]
  • sp: 表示机械臂运动的速度，取值范围是0-100
• 返回值： 无

3.11 get_radians()

• 功能： 获取所有关节的弧度
• 返回值： list包含所有关节弧度值的列表

3.12 send_radians(radians, speed)

• 功能： 发送弧度值给机械臂所有关节
• 参数说明：
  • radians:表示机械臂的弧度值
• 返回值： 无

3.13 sync_send_angles(degrees, speed, timeout=7)

• 功能： 同步发送角度，到达目标点返回
• 参数说明：
  • degrees: 每个关节的角度值列表( List[float])
  • speed: ( int)机械臂运动的速度，取值范围是0-100。
  • timeout：时间默认7s
• 返回值： 无

3.14 sync_send_coords(coords, speed, mode)

• 功能： 同步发送坐标，到达目标点返回
• 参数说明：
  • coords: 坐标值列表( List[float])，
    • 六轴：长度为 6，依次为 [x, y, z, rx, ry, rz]
    • 四轴：长度为 6，依次为 [x, y, z, rx]
  • speed: ( int)机械臂运动的速度，取值范围是0-100
• 返回值： 无

3.15 is_in_position(data, flag)

• 功能： 判断机器人有没有到达指定的位置
• 参数说明：
  • data: 您给出的一组数据可以是角度也可以是坐标值,如：[10,20,20,10,20,10]
  • flag: 数据类型(取值范围0或1)
    • 0: 表示给入的数值是角度值
    • 1: 表示给入的数值是坐标值
• 返回值： 1 - 已到达 0 - 未到达 -1 - 错误

3.16 is_moving()

• 功能： 判断机械臂有没有移动
• 返回值： 1 - 正在移动 0 - 没有移动 -1 - 错误

3.17 set_color(r, g, b)

• 功能： 设置机器人手臂顶部的灯光颜色(LED灯光控制)
• 参数说明： r，g，b表示机器人顶部的灯光颜色值
  • r: 0 ~ 255
  • g: 0 ~ 255
  • b: 0 ~ 255
• 返回值： 无

3.18 set_encoders_drag(encoders, speeds)

• 功能： 发送所有的电位值和速度
• 参数说明：
  • encoders：机械臂所有关节的电位值(list)
  • speed：机械臂所有关节的速度
• 返回值： 无

3.19 get_solution_angles()

• 功能： 获得偏转角度值(仅作用于MyArm)
• 返回值： 无

3.20 set_solution_angles(angle, speed)

• 功能： 设置偏转角度值(仅作用于MyArm)
• 参数说明：
  • angle：第一关节的角度
  • speed：速度(0 - 100)
• 返回值： 无

3.21 set_solution_angles(angle, speed)

• 功能： 设置偏转角度值(仅作用于MyArm)
• 参数说明：
  • angle：第一关节的角度
  • speed：速度(0 - 100)
• 返回值： 无

3.16 set_solution_angles(angle, speed)

• 功能： 设置偏转角度值(仅作用于MyArm)
• 参数说明：
  • angle：第一关节的角度
  • speed：速度(0 - 100)
• 返回值： 无

3.17 get_transponder_mode()

• 功能： 获得串口传输的配置信息(仅作用于MyArm)
• 返回值： 无
  • 0：关闭透传
  • 1：打开透传，检测所有数据
  • 2：打开透传，只检测通信转发模式的配置信息(默认为0)

3.18 set_transponder_mode(mode)

• 功能： 设置串口传输模式(仅作用于MyArm)
• 参数说明：
  • 0：关闭透传
  • 1：打开透传，检测所有数据
  • 2：打开透传，只检测通信转发模式的配置信息
• 返回值： 无

4 JOG 模式和操作

4.1 jog_angle(joint_id, direction, speed)

• 功能： 控制机器人按照指定的角度持续移动
• 参数说明：
  • joint_id: 代表机械臂的关节，按照关节id给入1~6来表示
  • direction: 主要控制机器臂移动的方向，给入0 为负值移动，给入1为正值移动
  • speed: 速度 0 ~ 100
• 返回值： 无

4.2 jog_coord(coord_id, direction, speed)

• 功能： 控制机器人按照指定的坐标或姿态值持续移动
• 参数说明：
  • coord_id：代表机械臂的关节，按照关节id给入1~6来表示
  • direction：主要控制机器臂移动的方向，给入0 为负值移动，给入1为正值移动
  • speed：速度 0 ~ 100
• 返回值： 无

4.3 jog_stop()

• 功能： 停止 jog 控制下的持续移动
• 返回值： 无

4.4 jog_absolute(joint_id, angle, speed)

• 功能： 控制机器人的特定关节运动到指定角度
• 参数说明：
  • joint_id：代表机械臂的关节，按照关节id给入1~6来表示
  • angle：指定关节运动的角度
  • speed：速度 0 ~ 100
• 返回值： 无

4.5 jog_increment(joint_id, angle, speed)

• 功能： 步进模式，使运动角度以给定的增量运行
• 参数说明：
  • joint_id：代表机械臂的关节，按照关节id给入1~6来表示
  • angle：增量范围
  • speed：速度 0 ~ 100
• 返回值： 无

5 舵机控制与操作

5.1 set_servo_calibration(servo_no)

• 功能： 校准指定关节，设置当前位置为角度零点，对应电位值为2048
• 参数说明： servo_no:(int)：机械臂的指定关节，mycobot系列范围为1~6，mypalletizer系列范围为1-4，myArm系列范围为1-7
• 返回值： 无

5.2 focus_servo(servo_id)

• 功能： 给指定关节上电
• 参数说明： servo id: (int)：机械臂的指定关节,mycobot系列范围为1~6，mypalletizer系列范围为1-4，myArm系列范围为1-7
• 返回值： 无

5.3 joint_brake(joint_id)

• 功能： 在关节运动的状态下使其停止运动，缓冲距离与现有速度正相关
• 参数说明： joint_id: (int)：机械臂的指定关节,范围为1~7
• 返回值： 无

5.4 get_servo_speeds()

• 功能： 获得关节运行速度
• 返回值： (list)每个关节的运行速度

5.5 get_servo_currents()

• 功能： 获得关节当前运行速度
• 返回值： (list)每个关节的速度

5.6 get_servo_voltages()

• 功能： 获得关节电压
• 返回值： (list)每个关节的电压

5.7 get_servo_status()

• 功能： 获得关节状态
• 返回值： (list)每个关节的状态

5.8 get_servo_temps()

• 功能： 获得关节的温度
• 返回值： (list)每个关节的温度

6 Atom 末端IO控制

6.1 set_pin_mode(pin_no, pin_mode)

• 功能： 设置 atom 中指定引脚的状态模式
• 参数说明：
  • pin_no (int)：机器人顶部的具体引脚号
  • pin_mode (int)： 限定0~2
    • 0设置为运行状态
    • 1设置为停止状态
    • 2设置为上拉模式
• 返回值： 无

6.2 set_digital_output(pin_no, pin_signa)

• 功能： 设置末端引脚号的工作状态
• 参数说明：
  • pin_no( int) 设备末端标注的编号仅取数字部分
  • pin_signal( int): 输入0表示设置为运行状态，输入1表示停止状态
• 返回值： 无

6.3 get_digital_input(self, pin_no):

• 功能： 获取末端引脚号的工作状态
• 参数说明: pin_no：表示机器人末端的具体引脚号
• 返回值： pin_signal( int) 当返回的值为0表示在工作状态运行，1表示停止状态

6.4 set_pwm_output(channel, frequency, pin_val):

• 功能： 脉宽调制控制
• 参数说明:
  • channel(int)：机器人顶部的具体引脚号
  • frequency(int):时钟频率
  • pin_val(int):占空比0~256；128为50%
• 返回值： 无

7 夹爪控制

7.1 is_gripper_moving( )

• 功能： 判断夹爪是否正在运行
• 返回值：
  • 0 ：表示机械臂的夹爪没有运行
  • 1 ：表示机械臂的夹爪正在运行
  • -1：表示出错

7.2 set_gripper_value(value, speed, gripper_type=None)

• 功能： 让夹爪以指定的速度转动到指定的位置
• 参数说明：
  • value：表示夹爪所要到达的位置，取值范围 0~100
  • speed：表示以多少的速度转动，取值范围 0~100
  • gripper_type：夹爪类型，默认是自适应夹爪
    • 1: 自适应夹爪
    • 3: 平行夹爪
    • 4: 柔性夹爪
• 返回值： 无

7.3 get_gripper_value(gripper_type=None)

• 功能： 获取夹爪的当前位置数据信息
• 参数说明：
  • gripper_type：夹爪类型，默认是自适应夹爪
    • 1: 自适应夹爪
    • 3: 平行夹爪
    • 4: 柔性夹爪
• 返回值： 夹爪的数据信息

7.4 set_gripper_state(flag, speed， _type=None)

• 功能： 让夹爪以指定的速度进入到指定的状态
• 参数说明：
  • flag：1 表示夹爪合拢状态，0 表示夹爪打开状态。
  • speed：表示以多快的速度达到指定的状态，取值范围 0~100
  • _type: 夹爪类型，默认是自适应夹爪
    • 1: 自适应夹爪
    • 2: 五指灵巧手
    • 3: 平行夹爪
    • 4: 柔性夹爪
• 返回值： 无

7.5 move_round()

• 功能： 驱动四子棋舵机逆时针转一圈，走完一圈需要1.5s

7.6 set_eletric_gripper(status)

• 功能： 设置夹爪模式(仅作用于350)
• 参数说明： status：1 表示夹爪合拢状态，0 表示夹爪打开状态。
• 返回值： 无

7.7 set_gripper_mode(status)

• 功能： 设置夹爪模式
• 参数说明： status：1 透传模式，0 I/O模式
• 返回值： 无

7.8 get_gripper_mode()

• 功能： 获取夹爪状态
• 返回值： status(int)：0 - 透传模式 1 - I/O模式

7.9 set_HTS_gripper_torque(torque)

• 功能： 设置自适应夹爪力矩
• 参数说明：
  • torque：150 ~ 900
• 返回值： 0 - 设置失败；1 - 设置成功

7.10 get_HTS_gripper_torque()

• 功能： 获取自适应夹爪力矩
• 返回值： 150 ~ 900

7.11 get_gripper_protect_current()

• 功能： 获取夹爪保护电流
• 返回值： 1 ~ 500

7.12 init_gripper()

• 功能： 初始化夹爪
• 返回值： 0 - 初始化失败；1 -初始化成功

7.13 set_gripper_protect_current(current)

• 功能： 设置夹爪保护电流
• 参数说明：
  • current：1 ~ 500
• 返回值： 0 - 初始化失败；1 -初始化成功

8 底座BasicIO控制

8.1 get_basic_input(pin_no)

• 功能： 获取底部引脚号的工作状态
• 参数说明: pin_no：表示机器人底部的具体引脚号。
• 返回值： pin_signal( int) 当返回的值为0表示在工作状态运行，1表示停止状态

8.2 set_basic_output(pin_no, pin_signal)

• 功能： 设置底部引脚号的工作状态。
• 参数说明：
  • pin_no( int) 设备底部标注的编号仅取数字部分
  • pin_signal( int): 输入0表示设置为运行状态，输入1表示停止状态
• 返回值： 无

9 socket 通信

机械臂需要开启服务端，服务端文件在这里.

# for mycobot,mecharm
from pymycobot import MyCobotSocket

mc = MyCobotSocket("192.168.1.10", 9000)

print(mc.get_angles())

10 TCPIP

10.1 set_ssid_pwd(account, password)

• 功能： 更改连接的wifi(适用于m5或seed)
• 参数说明:
  • account( str) ：新的 wifi 帐户
  • password( str)：新的 wifi 密码
• 返回值： 无

10.2 get_ssid_pwd()

• 功能： 获取连接的wifi账号和密码(适用于m5或seed)
• 返回值： 当前连接的wifi账号和密码

10.3 set_server_port(port)

• 功能： 更改服务器的连接端口
• 参数说明:
  • port( int) 服务器的新连接端口
• 返回值： 无

11 utils(模块)

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

from pymycobot import utils

11.1 utils.get_port_list()

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

11.2 utils.detect_port_of_basic()

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

12 树莓派——GPIO

当您的机械臂为树莓派版本时，您可以用到以下API。同时在使用API之前需在文件开头输入代码导入：

from pymycobot import MyCobot

12.1 gpio_init()

• 功能： 初始化 GPIO 模块，设置 BCM 模式
• 返回值： 无

12.2 set_gpio_mode

• 功能： 设置树莓派GPIO针脚模式
• 参数
  • mode (str) 输入："BCM" 或者 "BOARD" 进入相应模式

12.3 set_gpio_output(pin_no, state)

• 功能： 将引脚设置为高，低电平
• 参数说明:
  • pin( int) 引脚编号
  • state：0设置为低电平 1设置为高电平
• 返回值： 无

12.4 get_gpio_in(pin_no)

• 功能： 获取引脚电平状态
• 参数说明:
  • pin_no( int) 引脚编号
• 返回值： 0为低电平 1为高电平

12.5 gpio_output(pin,v)

• 功能： 设置GPIO输出值
• 参数说明:
  • pin_no( int) 引脚编号
  • v(int): 0设置为低电平 1设置为高电平
• 返回值： 无

12.6 set_gpio_out(pin_no, mode)

• 功能： 设置引脚作为输入或者输出
• 参数说明:
  • pin( int) 引脚编号
  • mode(str)：in - 输入 ； out - 输出
• 返回值： 无

13 坐标变换

13.1 get_tool_reference()

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

13.2 set_tool_reference(coords)

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

13.3 set_world_reference(coords)

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

13.4 get_world_reference()

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

13.5 set_reference_frame(rftype)

• 功能： 设置基坐标系
• 返回值： rftype: 0 - 基坐标(默认) 1 - 世界坐标

13.6 get_reference_frame()

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

13.7 set_movement_type(move_type)

• 功能： 设置移动类型
• 参数： move_type: 0 - movj 1 - movI
• 返回值： 无

13.8 get_movement_type()

• 功能： 获取移动类型
• 返回值： 0 - movj 1 - movI

13.9 set_end_type(end)

• 功能： 设置末端坐标系
• 参数： end: 0 - 法兰(默认) 1 - 工具
• 返回值： 无

13.10 get_end_type()

• 功能： 获取末端坐标系
• 返回值： 0 - 法兰(默认) 1 - 工具

14 速度规划

14.1 get_plan_speed()

• 功能： 获取规划速度
• 返回值： 移动速度(list)

14.2 get_plan_acceleration()

• 功能： 获取规划加速度
• 返回值： 加速度(list)