坐标系与工具管理接口

1. set_tool_hand_param - 设置工具手参数

方法： set_tool_hand_parameters(socket_fd: int, tool_num: int, tool_data: ToolParam)

功能描述： 通过配置并下发工具参数结构体（ToolParam），向机械臂控制器写入指定编号的工具手坐标系偏移参数。

参数：

socket_fd：已连接的机械臂控制器句柄，整型格式（int）。
tool_num：准备配置的工具手编号，整型格式（int）。
tool_data（底层输出参数）：工具手坐标属性结构体容器（对应代码中的 nrc.ToolParam()）。由方法内部自动创建并配置以下大写数组成员，无需外部手工创建。

返回值：

bool：执行结果布尔值
- True：参数写入成功。底层接口返回 0，新工具手参数成功同步至控制器。
- False：参数写入失败。句柄无效、传入的数据无法解析、底层的写入操作被拒绝、接口返回非 0 错误码或触发通信异常。

使用示例：

Python

import nrc_interface as nrc

# 1. 实例化官方定义的工具参数结构体容器
tool_data = nrc.ToolParam()

# 2. 精准配置核心测试参数（以 1 号工具手，XYZ各偏移 100mm 姿态不变为例）
tool_data.X = 100.0
tool_data.Y = 100.0
tool_data.Z = 100.0
tool_data.A = 0.0
tool_data.B = 0.0
tool_data.C = 0.0

# 3. 调用底层配置写入接口，指定写入到 1 号工具手
ret = nrc.set_tool_hand_param(socket_fd, 1, tool_data)

# 4. 校验指令下发结果并返回布尔状态
if ret == 0:
    print("成功: 1 号工具手核心测试参数成功写入控制器！")
    return True
else:
    print("错误: 工具手参数写入控制失败")
    return False

2. set_user_coordinate_data - 设置用户坐标

方法： set_user_coordinate_parameters(socket_fd: int, coord_num: int, pos_data: VectorDouble)

功能描述： 通过配置并下发位置向量数据（VectorDouble），向机械臂控制器写入指定编号的用户坐标系参数。用户坐标系多用于当机械臂在特定倾斜工作台或工件上作业时，进行相对坐标变换。

参数：

socket_fd：已连接的机械臂控制器句柄，整型格式（int）。
coord_num：准备配置的用户坐标系编号，整型格式（int），默认 1。
pos_data（底层输出参数）：用户坐标系偏移属性向量容器（对应代码中的 nrc.VectorDouble()）。由方法内部自动创建、扩容并配置以下核心数组成员，无需外部手工创建。

返回值：

bool：执行结果布尔值
- True：参数设置成功。底层接口返回 0，新用户坐标系参数成功同步至控制器。
- False：参数设置失败。句柄无效、坐标编号越界、传入的动态向量无法解析、接口返回非 0 错误码或触发通信异常。

使用示例：

Python

import nrc_interface as nrc

# 1. 实例化官方定义的动态数组容器以接收数据
pos_data = nrc.VectorDouble(6)

# 2. 精准配置核心测试参数（以 2 号用户坐标系，X 轴偏移 200mm，绕 Z 轴旋转 45° 为例）
test_origin = [200.0, 0.0, 0.0, 0.0, 0.0, 45.0]
for i in range(6):
    pos_data[i] = test_origin[i]

# 3. 调用底层配置写入接口，指定写入到 2 号用户坐标系
ret = nrc.set_user_coordinate_data(socket_fd, 2, pos_data)

# 4. 校验指令下发结果并返回布尔状态
if ret == 0:
    print("成功: 2 号用户坐标系核心测试参数成功写入控制器！")
    return True
else:
    print("错误: 用户坐标系参数设置失败")
    return False

3. set_user_coord_number - 设置用户坐标编号

方法： set_user_coordinate_number(socket_fd: int, coord_num: int)

功能描述： 切换并激活控制器当前使用的用户坐标系编号。激活后，后续所有基于用户坐标系（User）下发的空间直角运动指令，都将自动以该编号对应的坐标系原点及姿态作为参照基准。

参数：

socket_fd：已连接的机械臂控制器句柄，整型格式（int）。
coord_num：准备切换并激活的目标用户坐标系编号，整型格式（int），默认 1。

返回值：

bool：执行结果布尔值
- True：切换激活成功。底层接口返回 0，控制器成功完成当前坐标系的切换。
- False：切换激活失败。句柄无效、坐标系编号超出控制器规定范围、底层接口返回非 0 错误码或触发通信异常。

使用示例：

Python

import nrc_interface as nrc

# 1. 声明准备激活的用户坐标系编号（例如切换到已配置好的 2 号用户坐标系）
target_coord_num = 2

# 2. 调用底层接口执行激活切换
ret = nrc.set_user_coord_number(socket_fd, target_coord_num)

# 3. 校验指令执行状态并返回布尔结果
if ret == 0:
    print(f"成功: 控制器当前已成功切换并激活 {target_coord_num} 号用户坐标系！")
    return True
else:
    print("错误: 切换用户坐标系编号失败")
    return False

4. get_current_coord - 获取当前工作坐标系

方法： get_current_coordinate_system(socket_fd: int, coord_placeholder: int)

功能描述： 获取机器人控制器当前处于激活状态的工作坐标系类型（如关节、直角、工具或用户坐标系）。

参数：

socket_fd：已连接的机械臂控制器句柄，整型格式（int）。
coord_placeholder（底层输入参数）：接口技术规范要求的整型占位符参数（对应代码中的 0）。

返回值：

int：当前激活的坐标系编号
- 0：关节坐标系 / 基座坐标系（Joint / Base）
- 1：直角空间坐标系（Cartesian / Tool Center Point）
- 2：工具坐标系（Tool）
- 3：用户坐标系（User）
- -1：获取失败。句柄无效、底层接口返回非 0 错误码或触发通信异常。

使用示例：

Python

import nrc_interface as nrc

# 1. 定义底层协议帧对齐所必须的占位整型变量
coord_placeholder = 0

# 2. 调用底层解包接口，获取返回的状态码与坐标系实际值
ret_code, current_coord = nrc.get_current_coord(socket_fd, coord_placeholder)

# 3. 校验执行结果并返回对应的坐标系类型状态
if ret_code == 0:
    print(f"成功: 获取当前工作坐标系成功，当前激活的类型代号为: {current_coord}")
    return current_coord
else:
    print(f"错误: 获取当前工作坐标系失败，底层错误码: {ret_code}")
    return -1

5. set_current_coord - 切换示教运动坐标系

方法： set_current_coordinate_system(socket_fd: int, coord: int)

功能描述： 切换机械臂在手动示教、点动（Jogging）或者微调模式下的当前工作坐标系参照物。切换成功后，手动点动轴（或者通过某些实时控制操作）对应的运动方向将切换为新坐标系所定义的轴向。

参数：

socket_fd：已连接的机械臂控制器句柄，整型格式（int）。
coord：准备切换并激活的目标工作坐标系类型代号，整型格式（int），默认 0。
- 0：关节坐标系 / 基座坐标系（Joint / Base）
- 1：直角空间坐标系（Cartesian）
- 2：工具坐标系（Tool）
- 3：用户坐标系（User）

返回值：

bool：执行结果布尔值
- True：切换成功。底层接口返回 0，控制器成功完成当前示教工作坐标系的切换。
- False：切换失败。句柄无效、传入的坐标系类型代号超出范围（非 0~3）、底层接口返回非 0 错误码或触发通信异常。

使用示例：

Python

import nrc_interface as nrc

# 1. 声明准备切换的目标示教坐标系类型（例如切换到工具坐标系）
target_coord_type = 2

# 2. 调用底层接口执行切换
ret = nrc.set_current_coord(socket_fd, target_coord_type)

# 3. 校验指令执行状态并返回布尔结果
if ret == 0:
    print(f"成功: 控制器当前已成功切换示教坐标系为: {target_coord_type} (工具坐标系)！")
    return True
else:
    print("错误: 切换示教运动坐标系失败")
    return False