Python SDK 接口示例

注意

仅支持 Python 3.7 及以上版本
如果使用常规调用方式，请安装lebai-sdk： pip install lebai_sdk
如果使用异步协程调用方式，即AsyncIO及async/await，请安装: lebai-sdk-asyncio：pip install lebai_sdk_asyncio

初始化连接

设备发现

注意

本功能基于 mDNS 技术，用于 Web 前端开发的 JavaScript SDK 不支持该功能

devices = lebai_sdk.discover_devices(time)

在持续时间内连续发现周边设备，持续时间结束后，返回发现的设备的名称、IP、MAC 地址。

参数
- time 持续时间
返回
- 列表类型。列表里包含搜到的设备结果，每个设备对象的属性(设备的名称、IP、MAC 地址)以字典形式呈现
- name 设备的名称
- ip 设备IP
- mac 设备MAC 地址

示例程序

import lebai_sdk
lebai_sdk.init()
import nest_asyncio
nest_asyncio.apply()

devices = lebai_sdk.discover_devices(3)
print(devices)
# 输出：
# [{'name': 'lebai-3wbgvM', 'mac': 'b4:4b:d6:5e:55:1c', 'ip': '10.20.17.1', 'online': True}]

初始化对象

注意

由于通信不稳定,ip错误等原因，可能导致错误发生。大多数情况下，需要使用错误处理机制来捕获错误，防止异常退出。

lebai = lebai_sdk.connect(ip, simu)

连接到乐白机械臂

参数
- ip 乐白机械臂的 IP 地址
- simu 是否以仿真模式连接。可选，默认真机模式
返回
- lebai 机械臂实例，后续控制机械臂的方法需使用该实例

示例程序

import lebai_sdk
lebai_sdk.init()

# 如果出现event loop相关的RuntimeError，尝试添加以下2行
# import nest_asyncio
# nest_asyncio.apply()

# 设定机器人ip地址，需要根据机器人实际ip地址修改
robot_ip = "192.168.4.145" 
# 创建实例  
lebai = lebai_sdk.connect(robot_ip, False)

获取连接状态

connected = lebai.is_connected()

返回连接状态。用于判断是否处于连接状态，如果重启手臂会断连。

返回
- connected 连接状态

示例程序

import lebai_sdk
lebai_sdk.init()
import nest_asyncio
nest_asyncio.apply()
robot_ip = "192.168.4.123" 
try:
    lebai = lebai_sdk.connect(robot_ip, False) 
    connected = lebai.is_connected()
    if not connected:
        print('机器断连')
        disconnect_reason = lebai.wait_disconnect()
        print(disconnect_reason)

except Exception as e:
    print('初始化对象失败： %s'%e)

等待断开连接

disconnect_reason = lebai.wait_disconnect()

返回连接断开后的断开原因。如果检测到手臂断开连接，判断断开原因，重新连接。

返回
- disconnect_reason 断开连接的原因

示例程序

import lebai_sdk
lebai_sdk.init()
import nest_asyncio
nest_asyncio.apply()
robot_ip = "192.168.4.123" 
try:
    lebai = lebai_sdk.connect(robot_ip, False) 
    connected = lebai.is_connected()
    if not connected:
        print('机器断连')
        disconnect_reason = lebai.wait_disconnect()
        print(disconnect_reason)
        lebai = lebai_sdk.connect(robot_ip, False) 

except Exception as e:
    print('初始化对象失败： %s'%e)

状态数据

机器人状态获取

robot_state = lebai.get_robot_state()

返回当前机器人状态。

返回
- robot_state 机器人状态

状态详情如下：

状态码	状态	说明
-1	ERROR	机器人软件控制系统异常
0	DISCONNECTED	机器人硬件通讯故障
1	ESTOP	机器人处于急停状态，请确认安全性
2	BOOTING	机器人初始化中
3	ROBOT_OFF	机器人电源未开启
4	ROBOT_ON	机器人电源已开启
5	IDLE	机器人处于空闲状态
6	PAUSED	机器人处于暂停中状态
7	MOVING	机器人运动中
8	UPDATING	机器人系统更新中
9	STARTING	机器人初始化完成到空闲的启动过程中
10	STOPPING	机器人空闲状态转到停止状态
11	TEACHING	机器人处于示教模式中
12	STOP	机器人处于停止状态，非急停状态

注意

手臂是空闲状态时，当有场景调用，场景内执行非运动类指令，手臂状态仍是空闲状态，手臂状态和场景的执行有相对独立性。

示例程序

import lebai_sdk
lebai_sdk.init()
import nest_asyncio
nest_asyncio.apply()

robot_ip = "192.168.22.103" 
lebai = lebai_sdk.connect(robot_ip, False) 
print('机器人状态：',lebai.get_robot_state())  # 输出机器人状态： IDLE

获取急停原因

reason = lebai.get_estop_reason()

返回机器人导致急停的原因。

返回
- reason 急停原因

状态码	状态	说明
0	None	未急停
2	System	软件
3	Manual	手动调用接口
4	HardEstop	硬急停按钮
5	Collision	碰撞
6	JointLimit	关节限位
7	Exceed	超速
8	TrajectoryError	运动规划错误
11	CommError	通信故障
12	CanError	CAN通信故障
13	JointError	关节故障

示例程序

import lebai_sdk
lebai_sdk.init()
import nest_asyncio
nest_asyncio.apply()
robot_ip = "192.168.22.103" 
lebai = lebai_sdk.connect(robot_ip, False) 
print('机器人急停原因：',lebai.get_estop_reason())

获取当前运动数据

kin_data = lebai.get_kin_data()

返回当前机器人位置信息和速度信息等。

返回
- kin_data 包含运动数据的字典

返回字典包含以下内容：

actual_joint_pose 反馈关节位置
actual_joint_speed 反馈关节速度
actual_joint_acc 关节反馈加速度
actual_joint_torque 关节反馈力矩
target_joint_pose 规划关节位置
target_joint_speed 规划关节速度
target_joint_acc 关节规划加速度
target_joint_torque 关节规划力矩
actual_tcp_pose 反馈工具位置
target_tcp_pose 规划工具位置
actual_flange_pose 反馈法兰位置

示例程序

import lebai_sdk
lebai_sdk.init()
import nest_asyncio
nest_asyncio.apply()
robot_ip = "192.168.4.145" 
lebai = lebai_sdk.connect(robot_ip, False) 
status_dic = lebai.get_kin_data()  
print('反馈关节位置',status_dic['actual_joint_pose'])  
print('反馈笛卡尔位置',status_dic['actual_tcp_pose'])
# 输出
# 反馈关节位置 [1.2506737111230115, -0.7450352939162074, 1.673956534780206, -3.81232575309279, -1.855829131943897, -0.16701215828104918]
# 反馈笛卡尔位置 {'x': -0.05377600646795382, 'y': -0.4710049716677433, 'z': 0.27203923572072963, 'rx': -1.82541291265244, 'ry': -0.2336434403164556, 'rz': 2.587395211267338}

获取手臂物理数据

data = lebai.get_phy_data()

返回手臂关节温度和电压，以及末端法兰电压。

返回
- data 包含物理数据的字典

字典包含参数如下：

joint_temp 各个关节温度
joint_voltage 各个关节电压
flange_voltage 法兰盘电压

示例程序

import lebai_sdk
lebai_sdk.init()
import nest_asyncio
nest_asyncio.apply()
robot_ip = "192.168.4.145" 
lebai = lebai_sdk.connect(robot_ip, False) 
data = lebai.get_phy_data()  
print(data)
# 输出
# {'joint_temp': [34.0, 39.0, 35.0, 38.0, 41.0, 40.0], 'joint_voltage': [48.07, 47.94, 48.25, 47.86, 47.96, 48.09], 'flange_voltage': 23.33}

机器人系统控制

启动手臂

lebai.start_sys()

当机器人上电初始化后，处于电源已开启的上电状态，不能直接命令运动，使用此命令，使能关节运动，执行成功后机器人转为空闲状态。

当机器人处于已急停、已下电、已上电、已停止状态时，接受该指令。机器人处于其他状态时，该指令不会执行，也不会报错。

注意

如果机器人硬急停被按下，该指令触发错误 1011: 请释放硬件急停开关后重试。

示例程序

import lebai_sdk
lebai_sdk.init()
import nest_asyncio
nest_asyncio.apply()
robot_ip = "192.168.4.145" 
lebai = lebai_sdk.connect(robot_ip, False) 
lebai.start_sys()

停止手臂

lebai.stop_sys()

当机器人处于已上电、空闲、已暂停、运行中、示教中状态时，接受该指令，执行成功后机器人转为已停止状态。机器人处于其他状态时，该指令不会执行，也不会报错。

示例程序

import lebai_sdk
lebai_sdk.init()
robot_ip = "192.168.4.145" 
lebai = lebai_sdk.connect(robot_ip, False) 
lebai.stop_sys()

关机

lebai.powerdown()

该指令在任意已连接状态下均可执行。它会使机器人手臂和控制箱电源断开，同时网络连接也会中断。

如要关机后再次启动（电源开关处于打开状态），请按硬件开机按钮（机箱上圆形按钮）。如安装了上电开机模块（短接开机按钮，机箱上电就开机），请关闭电源并重新通电。

示例程序

import lebai_sdk
lebai_sdk.init()
import nest_asyncio
nest_asyncio.apply()
robot_ip = "192.168.4.145" 
lebai = lebai_sdk.connect(robot_ip, False) 
lebai.powerdown()

重启

lebai.reboot()

该指令会重新启动机箱，相当于按下开机按钮关机后，重新按开机按钮开机。

示例程序

import lebai_sdk
lebai_sdk.init()
import nest_asyncio
nest_asyncio.apply()
robot_ip = "192.168.4.145" 
lebai = lebai_sdk.connect(robot_ip, False) 
lebai.reboot()

急停

lebai.estop()

急停分为软急停和硬急停，该命令以及通过 App 操作的急停都是软急停，硬急停指拍机箱上的急停按钮。

指令执行时会立刻断开使机器人手臂下电并刹车，此时手臂会产生轻微的向下掉落。急停后，手臂将停止运动，法兰盘、灯板均停止工作，须调用start_sys() 重新给手臂上电。

注意

如果当前有其他任务和指令正在运行，急停会导致这些指令中断并且报错，并进一步导致相关未进行的任务运行失败。

示例程序

import lebai_sdk
lebai_sdk.init()
import nest_asyncio
nest_asyncio.apply()
robot_ip = "192.168.4.145" 
lebai = lebai_sdk.connect(robot_ip, False) 
lebai.estop()

运动

示教模式

lebai.teach_mode()

当机器人处于空闲状态时，调用该指令可进入示教（自由驱动）模式。在示教模式下，机器人各关节可被自由拖拽，故又称自由驱动模式。末端负载配置会影响示教效果，设置值比实际负载大时，机器人会向上用力，反之则会向下用力，请注意检查。

注意

当机器人处于非空闲状态时，调用该指令将会产生错误 1000: 机器人处于空闲中才能示教。

退出示教模式

lebai.end_teach_mode()

当机器人处于示教中状态，即示教（自由驱动）模式时，调用该指令可退出示教模式，恢复到空闲状态。处与其他模式时调用不产生错误。

关节运动

motion_id = lebai.movej(p, a, v, t, r)

参数
- p 位置参数。若是列表如 [0.1, 0.2, 0.2, 0.3, 0.1, 0.2]，表示关节角表达的关节位置；若是字典如 {'x': 0.01, 'y': 0, 'z': 0, 'rz': 0, 'ry':0, 'rx':0}，则表示笛卡尔坐标位置
- a 运动的关节加速度 (rad/s2)
- v 运动的关节速度 (rad/s)
- t 运动时间 (s)。当 t > 0 时，参数速度v和加速度a无效
- r 运动轨迹交融半径 (m)。用于指定路径的平滑效果，范围0到1
返回
- motion_id 运动指令id

注意

当位置参数是笛卡尔坐标位置时，如果输入的笛卡尔坐标位置是奇异点或者超出运动范围，反解不出来，就会报错。
安全设置里有各个关节的安全角度范围设置，如果输入的关节位置，某个关节角度超出范围，运动过程中会报错。

直线运动

motion_id = lebai.movel(p, a, v, t, r)

参数
- p 位置参数
- a 运动的工具空间加速度 (m/s2)
- v 运动的工具空间速度(m/s)
- t 运动时间 (s)
- r 运动轨迹交融半径 (m)
返回
- motion_id 运动指令id

等待运动完成

lebai.wait_move(motion_id)

参数
- motion_id 运动指令返回的motion_id，等待对应的运动指令执行完成。可选参数，默认为0，等待全部运动执行完成

获取运动状态

move_state = lebai.get_motion_state(motion_id)

参数
- motion_id 运动指令返回的motion_id
返回
- move_state 运动状态: "WAIT"排队中；"RUNNING"运动中；"FINISHED"已完成

暂停运动

lebai.pause_move()

暂停所有运动。不影响任务运行状态。

恢复运动

lebai.resume_move()

恢复所有运动。不影响任务运行状态。

停止运动

lebai.stop_move()

停止正在排队执行的所有运动，但无法取消后续新发的运动指令。

夹爪

夹爪指令需要在机器人法兰盘上安装原装的夹爪，该夹爪支持力控和位控。

注意

当机器人首次启动或重新上电时，夹爪将会自动张合一次以确认行程。请在启动机器人之前确认夹爪周围是否有障碍物遮挡。

初始化夹爪

lebai.init_claw(must)

初始化夹爪，夹爪张合一次以确认行程。需要新版本夹爪硬件支持。

参数
- must 是否强制执行初始化。可选，默认监测到夹爪初始化过就不初始化

夹爪控制

lebai.set_claw(force, amplitude)

设置夹爪力度（力控）和幅度（位控）。如果在闭合过程中,还未到达设置幅度，但是抓取到物体，夹爪力控达到设置的力的大小，则不再继续闭合以避免夹坏物体。

参数
- force 力度（0-100）。可选，默认不更改
- amplitude 张合幅度（0-100）。可选，默认不更改

获取夹爪状态

claw_status = lebai.get_claw()

返回
- claw_status 字典类型，包含 force（夹爪力度）、amplitude（夹爪张合幅度）等信息

程序任务控制

机器人的控制操作界面，自带Lua编辑器，可以用相应的Lua API编辑一段控制机器人的Lua代码，我们称之为场景，并有对应的场景ID。

启动任务

task_id = lebai.start_task(scene_id, params, dir, is_parallel, loop_to)

调用相应的场景scene_id，执行对应的任务。

参数
- scene_id 场景 ID
- params 传递参数。字符串数组。可选，默认空
- dir 场景所在文件名称。可选，默认根目录
- is_parallel 是否以并行任务并列执行。可选，默认false 以串行任务执行
- loop_to 重复执行次数。可选，默认 1 次，0 代表无限次
返回
- task_id 任务的id

注意

当被启动的场景里包含运动相关接口时，务必以串行任务启动(is_parallel为false)
在串行执行的场景任务中，如果场景中有用Lua API调用子任务，务必以并行任务启动(is_parallel为true)，否则将阻塞住

等待任务完成

stdout = lebai.wait_task(task_id)

参数
- task_id 任务 ID。可选，默认正在执行的串行任务
返回
- stdout 对应任务的所有print输出

获取任务状态

state = lebai.get_task_state(task_id)

参数
- task_id 任务 ID。可选，默认正在执行的串行任务
返回
- state 任务状态："NONE"无任务；"WAIT"排队中；"RUNNING"运行中；"PAUSE"暂停中；"SUCCESS"运行成功；"INTERRUPTING"停止中；"INTERRUPT"已停止；"FAIL"运行失败

停止任务

lebai.cancel_task(task_id)

停止指定任务。当停止串行任务时，会自动调用stop_move停止运动。

参数
- task_id 任务 ID。可选，默认正在执行的串行任务

IO控制

IO 设备类型：

"ROBOT"：控制箱，带有 4DI/4DO/2AI/2AO
"FLANGE"：法兰盘，带有 2DI/2DO
"EXTRA"：扩展板，带有 12DI/12DO/2AI/2AO
"SHOULDER"：肩部灯板，带有 1DI，已用作按键
"FLANGE_BTN"：法兰按钮，带有 2DI，已用作按键

设置数字输出

lebai.set_do(device, pin, value)

设置对应的DO端口打开和关闭。常用于控制电磁阀的开闭。

参数
- device 设备类型
- pin 端口，从 0 开始
- value 待设置的值，0 关闭/1 打开

获取数字输入

value = lebai.get_di(device, pin)

获取对应的DI端口是否有电信号输入。常用于光电传感器的检测。

参数
- device 设备类型
- pin 端口，从 0 开始
返回
- value 0无信号，1有信号

位置和位姿

正解

cart = lebai.kinematics_forward(jpose)

通过机器人正向运动学将关角度坐标转成笛卡尔位置和姿态表达的坐标。

参数
- jpose 关节位置
返回
- cart 笛卡尔空间位置和姿态

反解

joints = lebai.kinematics_inverse(pose, joints)

通过机器人逆向运动学反解，将笛卡尔位置和姿态转换成关节角度。计算结果与当前 TCP 设置和当前关节位置有关。

参数
- pose 笛卡尔位置和姿态
- joints 反解参考的关节位置。可选，默认为当前反馈关节位置
返回
- joints 关节位置

位姿特征坐标系转换

c = lebai.pose_trans(a, b)

a 为一个相对机器人底座世界坐标系变换后的新坐标系 {A}，b 是相对于坐标系 {A} 的位姿描述。最后返回b相对于机器人世界坐标系的位姿描述。

参数
- a 位姿 A
- b 位姿 B
返回
- c 位姿 C=AB

位姿的逆

c = lebai.pose_inverse(a)

用于求位姿 a 对应的齐次矩阵 A，A的逆的位姿描述。可用于求解位姿方程。

参数
- a 输入位姿
返回
- c A的逆矩阵对应的笛卡尔位置和位姿

位姿的加

pose = lebai.pose_add(base, delta, frame)

从base位置，往frame方向移动delta后的位姿。

参数
- base 起始位姿
- delta 位姿偏移量
- frame 位姿偏移量方向，仅姿态部分有效。可空，默认基座方向
返回
- pose 移动后的位姿

机器人配置

设置 TCP

lebai.set_tcp(tcp)

设置工具中心点（TCP）坐标，坐标值相对于法兰盘末端工具坐标系。仅在运动学上有意义。

参数
- tcp 相对于法兰的偏移量，包含 x、y、z、rx、ry、rz

获取当前TCP

tcp = lebai.get_tcp()

返回
- tcp 当前机器人工具中心点（TCP）设置

设置速度因子

lebai.set_velocity_factor(factor)

以手臂运动命令的速度为基准，设置实际速度为运动命令速度的对应百分比。

参数
- factor 速度因子百分比，范围 0~100

设置机器人末端负载

lebai.set_payload(mass, cog)

当负载的重量或者重量分布发生变化时，必须调用该方法更新。

参数
- mass 负载质量，单位：kg。可选，默认不更新
- cog 质心，相对于法兰的偏移量。可选，默认不更新

设置重力方向

lebai.set_gravity(gravity)

设置机器人重力加速度的方向。

参数
- gravity 重力加速度的方向

正装方向：{"x": 0, "y": 0, "z": -9.8}；侧装方向：{"x": 0, "y": -9.8, "z": 0}；倒装方向：{"x": 0, "y": 0, "z": 9.8}

信号量交互

系统内置 256 个信号量，下标从 0 开始到 255。每个信号量都可以存储一个 32 位整数类型值，取值范围 -2147483648~2147483647。系统重新启动后，所有信号量都会被重新置为 0。

设置信号量

lebai.set_signal(index, value)

设置对应信号量的值。

参数
- index 信号量下标
- value 设置的信号量值

获取信号量

value = lebai.get_signal(index)

获取对应信号量的值。

参数
- index 信号量下标
返回
- value 对应信号量的值

# Python SDK 接口示例

# 初始化连接

# 设备发现

# 初始化对象

# 获取连接状态

# 等待断开连接

# 状态数据

# 机器人状态获取

# 获取急停原因

# 获取当前运动数据

# 获取手臂物理数据

# 机器人系统控制

# 启动手臂

# 停止手臂

# 关机

# 重启

# 急停

# 运动

# 示教模式

# 退出示教模式

# 关节运动

# 直线运动

# 等待运动完成

# 获取运动状态

# 暂停运动

# 恢复运动

# 停止运动

# 夹爪

# 初始化夹爪

# 夹爪控制

# 获取夹爪状态

# 程序任务控制

# 启动任务

# 等待任务完成

# 获取任务状态

# 停止任务

# IO控制

# 设置数字输出

# 获取数字输入

# 位置和位姿

# 正解

# 反解

# 位姿特征坐标系转换

# 位姿的逆

# 位姿的加

# 机器人配置

# 设置 TCP

# 获取当前TCP

# 设置速度因子

# 设置机器人末端负载

# 设置重力方向

# 信号量交互

# 设置信号量

# 获取信号量

Python SDK 接口示例

初始化连接

设备发现

初始化对象

获取连接状态

等待断开连接

状态数据

机器人状态获取

获取急停原因

获取当前运动数据

获取手臂物理数据

机器人系统控制

启动手臂

停止手臂

关机

重启

急停

运动

示教模式

退出示教模式

关节运动

直线运动

等待运动完成

获取运动状态

暂停运动

恢复运动

停止运动

夹爪

初始化夹爪

夹爪控制

获取夹爪状态

程序任务控制

启动任务

等待任务完成

获取任务状态

停止任务

IO控制

设置数字输出

获取数字输入

位置和位姿

正解

反解

位姿特征坐标系转换

位姿的逆

位姿的加

机器人配置

设置 TCP

获取当前TCP

设置速度因子

设置机器人末端负载

设置重力方向

信号量交互

设置信号量

获取信号量