API说明

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

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

#适用于MyPalletizer系列
from pymycobot.mypalletizer import MyPalletizer

#适用于mybuddy系列
from pymycobot.mybuddy import MyBuddy

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

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- 错误

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) 您所指定的关节，范围为1~6
返回值： angle: 返回来的度数

2.8 get_joint_max_angle(joint_id)

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

2.9 is_servo_enable(servo id)

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

2.10 is_all_servo_enable()

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

2.11 release_servo(servo_id)

功能： 放松指定的关节
参数说明： servo id: (int)机械臂的指定关节,范围为1~6
返回值： 无

2.12 get_tof_distance()

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

2.13 get_error_information()

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

2.14 clear_error_information()

功能： 清除错误信息

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
返回值： 无

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 控制下的持续移动
返回值： 无

5 舵机控制与操作

5.1 set_servo_data(servo_no, data_id, value)

功能： 设置舵机指定地址的数据参数
参数说明：
- servo_no：舵机的序列号，按照关节id给入1 - 6
- data_id：数据地址
- value: 取值范围0 - 4096
返回值： 无

5.2 get_servo_data(servo_no, data_id)

功能： 读取舵机指定地址的数据参数。
参数说明：
- servo_no：各个舵机的序列号，按照关节id给入1 - 6
- data_id：数据地址
返回值： 数据参数值，范围0-4096

5.3 set_servo_calibration(servo_no)

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

5.4 focus_servo(servo_id)

功能： 给指定关节上电
参数说明： servo id: (int)：机械臂的指定关节,范围为1~6
返回值： 无

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表示停止状态

7 夹爪控制

7.1 is_gripper_moving( )

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

7.2 set_gripper_value(value, speed)

功能： 让夹爪以指定的速度转动到指定的位置
参数说明：
- value：表示夹爪所要到达的位置，取值范围 0~256
- speed：表示以多少的速度转动，取值范围 0~100
返回值： 无

7.3 get_gripper_value()

功能： 获取夹爪的encoder数据信息
返回值： 夹爪的数据信息

7.4 set_gripper_ini()

功能： 设置夹爪初始化位置，设置当前位置为 2048
返回值： 无

7.5 set_gripper_state(flag, speed)

功能： 让夹爪以指定的速度进入到指定的状态
参数说明：
- flag：1 表示夹爪合拢状态，0 表示夹爪打开状态。
- speed：表示以多快的速度达到指定的状态，取值范围 0~100
返回值： 无

7.6 set_gservo_round(value)

功能： 控制9g舵机顺时针转一圈
参数说明：
- angle (int) 0 - 255. 0 : 停止 255 : 一直转 1 ~ 254: 数值加1就旋转30° (1->30°, 2->60°)

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为高电平

2 API说明