基础状态查询接口

头文件：include/tl_interface.h

1. get_current_position - 获取机械臂当前坐标信息

方法：get_current_position(socketFd, coord, pos);

功能描述：获取机器人当前位置。

参数：

socketFd：已连接的句柄。
coord：坐标系类型。
- 0：关节坐标系。
- 1：直角坐标系。
- 2：工具坐标系。
pos：输出参数，用于存储当前位置的向量。

返回值：

0：成功
非 0：失败

使用示例：

Python

import tl_interface as tl

# 建立连接

socket_fd = tl.connect_robot("192.168.1.13", "6001")

# 获取关节坐标系下的当前位置

current_pos = tl.VectorDouble()

coord = 0 # 关节坐标系

ret = tl.get_current_position(socket_fd, coord, current_pos)

if ret == 0:

    pos_list = list(current_pos)

    print(f"获取位置成功：{pos_list}")

else:

    print(f"获取位置失败，错误码：{ret}")

2. get_robot_running_state - 获取作业文件运行状态

方法：get_robot_running_state(SOCKETFD socketFd, int& status);

功能描述：获取当前作业文件的运行状态，执行前需要延时0.1秒。

参数：

socketFd：已连接的句柄。
status：程序运行状态，0 停止 1 暂停 2 运行。

返回值：

0：成功
非 0：失败

使用示例：

Python

import tl_interface as tl

# 建立连接

socket_fd = tl.connect_robot("192.168.1.13", "6001")

time.sleep(0.1)

status = 0

ret, status = tl.get_robot_running_state(socket_fd, status)

if ret != SUCCESS:

    print("[ERROR] 获取机械臂运行状态失败，程序退出!")

else:

    if status == 0:

        print("[INFO] 机械臂处于停止状态 (status = " + str(status) + ")")

    elif status == 1:

        print("[INFO] 机械臂处于暂停状态 (status = " + str(status) + ")")

    elif status == 2:

        print("[INFO] 机械臂处于运行状态 (status = " + str(status) + ")")

3. get_servo_state - 获取伺服状态

方法：get_servo_state(SOCKETFD socketFd, int& status);

功能描述：获取机械臂当前伺服状态信息。

参数：

socketFd：已连接的句柄。
status 接收获取结果 0：停止状态 1：就绪状态 2：报警状态 3：运行状态。

返回值：

0：成功
非 0：失败

使用示例：

Python

 # 2. 检查伺服状态

state = -1

ret, state = get_servo_state(socket_fd, state)

if ret != SUCCESS:

    print(f"[ERROR] 获取伺服状态失败: {ret}")

    return

print(f"  [信息] 当前伺服状态: {state} (0=停止 1=就绪 2=报警 3=运行)")

if state == 2:

    print("[ERROR] 伺服处于报警状态，无法上电，请排查报警原因后重试")

    return

if state == 3:

    print("[INFO] 机械臂已在使能上电状态")

    return

4. get_current_mode - 获取机器人当前模式

方法：get_current_mode(SOCKETFD socketFd, int& mode);

功能描述：获取机械臂当前模式。

参数：

socketFd：已连接的句柄
mode：当前模式 0：示教 1：远程 2：运行。

返回值：

0：成功
非 0：失败

使用示例：

Python

# ---- 检查模式并确保伺服运行 ----

# 先获取当前模式

current_mode = -1

ret, current_mode = get_current_mode(sock, current_mode)

if ret != SUCCESS or current_mode < 0:

    print("[ERROR] 获取当前模式失败: " + str(ret))

    disconnect_robot(sock)

    return -1

print("  [信息] 当前模式: " + str(current_mode) + " (0=示教 1=远程 2=运行)")

5. get_robot_dh_param - 获取机械臂 DH 参数

方法：get_robot_dh_param(SOCKETFD socketFd, RobotDHParam& param);

参数：

socketFd：已连接的句柄。
param：输出参数，RobotDHParam 结构体，包含 alpha/a/theta/d（标准 DH 参数双精度数组）、eulerAngle（欧拉角）、mountingAngle（安装角）等成员。

返回值：

0：成功
非 0：失败

使用示例：

Python

import tl_interface as tl

# 建立连接

socket_fd = tl.connect_robot("192.168.1.13", "6001")

dh_params = tl.RobotDHParam()

ret = tl.get_robot_dh_param(socket_fd, dh_params)

if ret == 0:

    print("alpha=" + str(list(dh_params.alpha)))

    print("a=" + str(list(dh_params.a)))

    print("theta=" + str(list(dh_params.theta)))

    print("d=" + str(list(dh_params.d)))

    print("eulerAngle=" + str(dh_params.eulerAngle))

    print("mountingAngle=" + str(dh_params.mountingAngle))

else:

    print(f"获取机械臂DH参数失败，错误码：{ret}")

6. get_library_version - 读取机械臂软件信息

方法：get_library_version();

功能描述：获取 SDK 库版本信息。

参数：

None

返回值：

str：成功返回版本信息字符串，格式 "<sdk版本>(Base:<base版本>)"，如 "V2.5.1-0-gabc1234-20260916(Base:2.0.4-20260914-6cf4a3b)"。

使用示例：

Python

import tl_interface as tl

# 获取库版本

version = tl.get_library_version()

print(f"机器人库版本 = {version}")

7. get_robot_joint_param - 获取关节参数

方法：get_robot_joint_param(socketFd, id, param);

功能描述：获取指定关节参数。

参数：

socketFd：已连接的句柄。
id：关节轴号，1~7 代表第 1~7 轴。
param：输出参数，用于存储关节参数的结构体。

返回值：

0：成功
非 0：失败

使用示例：

Python

import tl_interface as tl

# 建立连接

socket_fd = tl.connect_robot("192.168.1.13", "6001")

# 创建关节参数对象

joint_param = tl.RobotJointParam()

# 获取第 1 轴参数

ret = tl.get_robot_joint_param(socket_fd, 1, joint_param)

if ret == 0:

    print(f"返回值(ret) = {ret}")

    print(f"减速比 = {joint_param.reduceRatio}")

    print(f"额定转速 = {joint_param.ratedRotSpeed}")

    print(f"最大加速度 = {joint_param.maxAcc}")

    print(f"电机方向 = {joint_param.motorDirection}")

    print(f"正向软限位 = {joint_param.maxPos}")

    print(f"负向软限位 = {joint_param.minPos}")

else:

    print(f"获取关节参数失败，错误码：{ret}")

8. query_joint_software_version - 查询指定关节轴的软件版本号

方法：query_joint_software_version(socketFd, axisNum);

功能描述：查询指定关节（轴）的软件版本号。

参数：

socketFd：已连接的句柄。
axisNum：轴编号

返回值：

tuple：(ret, version)，ret 为执行结果，version 为查询到的软件版本号字符串。
0：成功。
非 0：失败。

使用示例：

Python

import tl_interface as tl

# 建立连接

socket_fd = tl.connect_robot("192.168.1.13", "6001")

# 查询 J1~J7 关节软件版本号

for i in range(1, 8):

    ret, version = tl.query_joint_software_version(socket_fd, i)

    if ret == 0:

        print(f"关节{i} 软件版本: {version}")

    else:

        print(f"查询关节{i}软件版本失败，错误码: {ret}")

9. get_nexmotion_lib_version - 获取底层 nexmotion 库版本信息

方法：get_nexmotion_lib_version(socketFd);

功能描述：获取算法库版本。

参数：

socketFd：已连接的句柄。

返回值：

tuple：(ret, version)，version 为算法库版本号字符串
0：成功
非 0：失败

使用示例：

Python

import tl_interface as tl

socket_fd = tl.connect_robot("192.168.1.13", "6001")

ret, version = tl.get_nexmotion_lib_version(socket_fd)

10. get_robot_state - 获取机器人整体状态

方法：get_robot_state(socketFd, param);

功能描述：7000 端口查询状态。

参数：

socketFd：已连接的句柄（7000 端口）。
param：RobotState 结构体，查询参数（channel 查询通道，最多 9 个通道；ioState 查询 IO；position 0-关节坐标 1-基坐标；dataildmotionpos 机械臂运动点位；programRunStatus 运行状态；servoStatus 伺服状态；operationMode 操作模式；globalSpeed 全局速度等）。

返回值：

0：成功
非 0：失败

使用示例：

Python

import tl_interface as tl

# 7000 端口建立连接（机器人状态查询走 7000）

socket_fd_7000 = tl.connect_robot("192.168.1.13", "7000")

# 构造查询参数（单次回复）

param = tl.RobotState()

param.channel = 1

param.stop = False

param.mode = 0                # 0-查询只回复一次 1-持续回复

param.interval = 1000

param.position = 0            # 0-关节坐标 1-直角坐标

param.servoStatus = True

param.programRunStatus = True

ret = tl.get_robot_state(socket_fd_7000, param)

if ret == 0:

    print("机器人状态查询请求已发送，等待回调")

# 停止持续推送并断开

stop_param = tl.RobotState()

stop_param.channel = 1

stop_param.stop = True

tl.get_robot_state(socket_fd_7000, stop_param)

tl.disconnect_robot(socket_fd_7000)

11. get_robot_type - 获取机器人类型

方法：get_robot_type(socketFd, type);

功能描述：获取机器人类型（返回机器人类型编号）。

参数：

socketFd：已连接的句柄。
type：传入占位值（RobotType 枚举成员或 int），实际类型以返回值为准。

RobotType 枚举说明：

枚举值	数值	说明
SIX_AXIS_SERIAL	1	六轴串联多关节
FOUR_AXIS_SCARA	2	四轴 SCARA
FOUR_AXIS_PALLETIZING	3	四轴码垛
FOUR_AXIS_SERIAL	4	四轴串联多关节
SINGLE_AXIS	5	单轴
FIVE_AXIS_SERIAL	6	五轴串联多关节
SIX_AXIS_COLLABORATIVE	7	六轴协作
TWO_AXIS_SCARA	8	二轴 SCARA
THREE_AXIS_SCARA	9	三轴 SCARA
THREE_AXIS_CARTESIAN	10	三轴直角
THREE_AXIS_SPECIAL	11	三轴异形
SEVEN_AXIS_SERIAL	12	七轴串联多关节
SCARA_SPECIAL	13	SCARA 异形一
FOUR_AXIS_PALLETIZING_LEAD	14	四轴码垛丝杆

返回值：

tuple：(ret, type)，ret 为执行结果，type 为机器人类型（RobotType 枚举）
0：成功
非 0：失败

使用示例：

Python

import tl_interface as tl

socket_fd = tl.connect_robot("192.168.1.13", "6001")

# 第 2 个参数为占位值，实际类型以返回值为准
ret, robot_type = tl.get_robot_type(socket_fd, tl.RobotType.SIX_AXIS_SERIAL)

if ret == 0:

    print(f"机器人类型：{robot_type}，编号：{int(robot_type)}")

12. get_current_line_speed_and_joint_speed - 获取当前线速度与关节速度

方法：get_current_line_speed_and_joint_speed(socketFd, joint_speed, joint_speed_sync);

功能描述：获取当前末端线速度和关节速度。

参数：

socketFd：已连接的句柄。
joint_speed：输出参数，关节速度，长度 7，单位度/s（需传入 VectorDouble 实例）。
joint_speed_sync：输出参数，外部轴关节速度，长度 5，单位度/s（需传入 VectorDouble 实例）。

返回值：

tuple：(ret, line_speed)，ret 为执行结果、line_speed 为末端线速度 mm/s
0：成功
非 0：失败

使用示例：

Python

import tl_interface as tl

socket_fd = tl.connect_robot("192.168.1.13", "6001")

# 出参必须传 VectorDouble 实例

joint_speed = tl.VectorDouble()        # 关节速度，长度 7

joint_speed_sync = tl.VectorDouble()   # 外部轴关节速度，长度 5

ret, line_speed = tl.get_current_line_speed_and_joint_speed(socket_fd, joint_speed, joint_speed_sync)

if ret == 0:

    print(f"末端线速度: {line_speed} mm/s")

    print(f"关节速度: {list(joint_speed)}")

    print(f"外部轴关节速度: {list(joint_speed_sync)}")

13. get_pos_reachable - 查询点位可达性

方法：get_pos_reachable(socketFd, pos, movetype, result);

功能描述：检测目标点位是否可达。

参数：

socketFd：已连接的句柄。
pos：目标点位坐标数据，vector 长度 14（[0]坐标系 0:关节 1:直角 2:工具 3:用户；[1]单位 0:角度 1:弧度；[2]形态；[3]工具手坐标序号；[4]用户坐标序号；[5][6]备用；[7-13]点位信息）。
movetype：移动方式，"MOVJ" 或 "MOVL"。
result：输出参数，点位是否可达（true=可达）。

返回值：

tuple：(ret, result)，ret 为执行结果、result 为点位是否可达
0：成功
非 0：失败

使用示例：

Python

import tl_interface as tl

socket_fd = tl.connect_robot("192.168.1.13", "6001")

# 目标点位 14 位: [7-13] 为点位值

pos = tl.VectorDouble([0, 0, 0, 0, 0, 0, 0, 20.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0])

ret, reachable = tl.get_pos_reachable(socket_fd, pos, "MOVJ", False)

if ret == 0:

    print(f"点位可达：{reachable}")

14. robot_state_callback - 注册机器人状态回调

方法：robot_state_callback(socketFd, function);

功能描述：7000 端口状态返回的回调函数，状态变化时自动调用 function。

参数：

socketFd：已连接的句柄（7000 端口）。
function：回调函数，接收状态字符串参数。

返回值：

0：成功
非 0：失败

使用示例：

Python

import tl_interface as tl

# 7000 端口建立连接（状态回调走 7000）

socket_fd_7000 = tl.connect_robot("192.168.1.13", "7000")

# 定义状态回调（回调在独立线程触发，不能做耗时操作）

def on_robot_state(state):

    print(f"[回调] 收到状态：{state}")

# 注册回调

ret = tl.robot_state_callback(socket_fd_7000, on_robot_state)

if ret == 0:

    print("状态回调注册成功")

15. get_speed - 获取速度

方法：get_speed(socketFd, speed);

功能描述：获得当前模式的速度。

参数：

socketFd：已连接的句柄。
speed：速度大小，0~100。

返回值：

tuple：(ret, speed)，ret 为执行结果、speed 为当前速度 0~100
0：成功
非 0：失败

使用示例：

Python

import tl_interface as tl

socket_fd = tl.connect_robot("192.168.1.13", "6001")

speed = 0

ret, speed = tl.get_speed(socket_fd, speed)

if ret == 0:

    print(f"当前速度: {speed} (0<speed≤100 百分比)")

else:

    print(f"获取速度失败，错误码：{ret}")

16. get_cartesian_params - 获取笛卡尔参数

方法：get_cartesian_params(socketFd, param);

功能描述：获取笛卡尔空间参数。

参数：

socketFd：已连接的句柄。
param：CartesianParam 输出参数（maxSpeed 最大线速度 mm/s；maxAcc 最大线加速度 mm/s^2；maxDec 最大线减速度 mm/s^2；maxAttitudeVel 最大姿态角速度 deg/s；speedLimitMode 速度限制方式；posResolution 绝对位置分辨率；maxJerk 最大线加加速度 mm/s^3 等）。

返回值：

0：成功
非 0：失败

使用示例：

Python

import tl_interface as tl

socket_fd = tl.connect_robot("192.168.1.13", "6001")

param = tl.CartesianParam()

ret = tl.get_cartesian_params(socket_fd, param)

if ret == 0:

    print(f"最大线速度：{param.maxSpeed} mm/s")

17. get_joint_position - 查询指定关节位置

方法：get_joint_position(socketFd, axisNum, pos);

功能描述：查询指定关节在基坐标系中的位置。

参数：

socketFd：已连接的句柄。
axisNum：关节轴号（如 1 表示 J1 轴）。
pos：输出参数，关节位置坐标（需传入 VectorDouble 实例）。

返回值：

0：成功。
非 0：失败。

使用示例：

Python

import tl_interface as tl

# 建立连接

socket_fd = tl.connect_robot("192.168.1.13", "6001")

pos = tl.VectorDouble()        # 输出参数，需传入 VectorDouble 实例

# 查询 J1 轴位置

ret = tl.get_joint_position(socket_fd, 1, pos)

if ret == 0:

    print(f"J1 位置: {list(pos)}")

else:

    print(f"查询失败，错误码：{ret}")