工具手相关接口

头文件：include/tl_interface.h
相关示例代码：examples\cpp\ex_tool_hand_number.cpp、examples\cpp\ex_coord_tool.cpp、examples\cpp\ex_info_query.cpp

1. set_tool_hand_number - 设置工具手编号

方法：Result set_tool_hand_number(SOCKETFD socketFd, int toolNum);

功能描述：设定末端工具对应的工具组编号，用于控制器匹配工具坐标系、负载参数及碰撞检测包络配置。

参数：

socketFd：已连接的句柄。
toolNum：工具手编号。

返回值：

0：成功。
非0：失败。

使用示例：

C++

    // 设置工具手编号为 2
    int tool_num = 2;
    auto ret = tl::set_tool_hand_number(socket_fd, tool_num);
    if (ret != tl::Result::SUCCESS) {
        std::cerr << "[ERROR] 设置工具手编号失败，错误码: " << ret << std::endl;
        return -1;
    }
    std::cout << "[信息] 设置工具手编号成功（toolNum = " << tool_num << "）" << std::endl;

2. get_tool_hand_number - 获取当前工具手编号

方法：Result get_tool_hand_number(SOCKETFD socketFd, int& toolNum);

功能描述：获取当前使用的工具手编号。

参数：

socketFd：已连接的句柄。
toolNum：输出，当前使用的工具手编号。

返回值：

0：成功。
非0：失败。

使用示例：

C++

    // 获取当前工具手编号（set 后需加延迟再 get，确保读取到最新值）
    std::this_thread::sleep_for(std::chrono::milliseconds(500));
    int get_tool_num = -1;
    auto ret = tl::get_tool_hand_number(socket_fd, get_tool_num);
    if (ret != tl::Result::SUCCESS) {
        std::cerr << "[ERROR] 获取工具手编号失败，错误码: " << ret << std::endl;
        return -1;
    }
    std::cout << "[信息] 当前工具手编号: " << get_tool_num << std::endl;

3. set_tool_hand_param - 设置工具手参数

方法：Result set_tool_hand_param(SOCKETFD socketFd, int toolNum, ToolParam param);

功能描述：设置指定工具手的参数（工具坐标系偏移、负载等）。

参数：

socketFd：已连接的句柄。
toolNum：工具手编号。
param：工具手参数结构体（ToolParam），可设置以下成员：
- X / Y / Z：X / Y / Z 轴偏移，单位 mm
- A / B / C：绕 A / B / C 轴旋转，单位度
- payloadMass：负载质量，单位 kg
- payloadInertia：负载惯量
- payloadMassCenter_X / Y / Z：负载质心，单位 mm
- note：注释
- maxToolRangeX / Y / Z、minToolRangeX / Y / Z：工具干涉区最大 / 最小范围
- toolHandMethod：工具手方式，0：控制点 1：立方体

返回值：

0：成功。
非0：失败。

使用示例：

C++

    // 设置工具手参数（编号 1）
    int tool_num = 1;
    tl::ToolParam tool_param;
    tool_param.X = 0;     // X 轴偏移 (mm)
    tool_param.Y = 0;     // Y 轴偏移 (mm)
    tool_param.Z = 0;     // Z 轴偏移 (mm)
    tool_param.A = 0;     // 绕 A 轴旋转 (度)
    tool_param.B = 0;     // 绕 B 轴旋转 (度)
    tool_param.C = 0;     // 绕 C 轴旋转 (度)

    auto ret = tl::set_tool_hand_param(socket_fd, tool_num, tool_param);
    if (ret != tl::Result::SUCCESS) {
        std::cerr << "[ERROR] 设置工具手参数失败，错误码: " << ret << std::endl;
        return -1;
    }
    std::cout << "[信息] 设置工具手参数成功" << std::endl;

4. get_tool_hand_param - 获取当前工具手参数

方法：Result get_tool_hand_param(SOCKETFD socketFd, int toolNum, ToolParam& param);

功能描述：获取指定工具手的参数（结构体成员同 3.）。

参数：

socketFd：已连接的句柄。
toolNum：工具手编号。
param：输出，工具手参数结构体（ToolParam）。

返回值：

0：成功。
非0：失败。

使用示例：

C++

    // 获取工具手参数（编号 1）
    int tool_num = 1;
    tl::ToolParam tool_param;
    auto ret = tl::get_tool_hand_param(socket_fd, tool_num, tool_param);
    if (ret != tl::Result::SUCCESS) {
        std::cerr << "[ERROR] 获取工具手参数失败，错误码: " << ret << std::endl;
        return -1;
    }
    std::cout << "[信息] 工具手 " << tool_num << " 参数:" << std::endl;
    std::cout << "  X=" << tool_param.X << " Y=" << tool_param.Y
              << " Z=" << tool_param.Z << std::endl;
    std::cout << "  A=" << tool_param.A << " B=" << tool_param.B
              << " C=" << tool_param.C << std::endl;

5. set_tool_coordinate_range - 设置工具包络球参数（工具坐标范围参数）

方法：Result set_tool_coordinate_range(SOCKETFD socketFd, int tool_number, const ToolCoordinateRange& range_param);

功能描述：设置工具坐标范围参数（工具包络球），用于碰撞检测包络计算。

参数：

socketFd：已连接的句柄。
tool_number：工具编号。
range_param：工具坐标范围参数结构体（ToolCoordinateRange）：
- min_range_x / max_range_x：X 轴最小 / 最大范围
- min_range_y / max_range_y：Y 轴最小 / 最大范围
- min_range_z / max_range_z：Z 轴最小 / 最大范围
- tool_hand_method：工具握持方式

返回值：

0：成功。
非0：失败。

使用示例：

C++

    // 设置工具坐标范围参数（编号 1）
    int tool_number = 1;
    tl::ToolCoordinateRange range_param;
    range_param.min_range_x = -500.0;
    range_param.max_range_x = 500.0;
    range_param.min_range_y = -400.0;
    range_param.max_range_y = 400.0;
    range_param.min_range_z = -300.0;
    range_param.max_range_z = 300.0;
    range_param.tool_hand_method = 1;

    auto ret = tl::set_tool_coordinate_range(socket_fd, tool_number, range_param);
    if (ret != tl::Result::SUCCESS) {
        std::cerr << "[ERROR] 设置工具" << tool_number << "坐标范围参数失败，错误码: " << ret << std::endl;
        return -1;
    }
    std::cout << "[信息] 设置工具坐标范围参数成功" << std::endl;

6. get_tool_coordinate_range - 获取工具包络球参数（工具坐标范围参数）

方法：Result get_tool_coordinate_range(SOCKETFD socketFd, int tool_number, ToolCoordinateRange& range_param);

功能描述：获取指定工具的坐标范围参数（工具包络球，结构体成员同 5.）。

参数：

socketFd：已连接的句柄。
tool_number：工具编号。
range_param：输出，工具坐标范围参数结构体（ToolCoordinateRange）。

返回值：

0：成功。
非0：失败。

使用示例：

C++

    // 获取工具坐标范围参数（编号 1）
    int tool_number = 1;
    tl::ToolCoordinateRange range_param;
    auto ret = tl::get_tool_coordinate_range(socket_fd, tool_number, range_param);
    if (ret != tl::Result::SUCCESS) {
        std::cerr << "[ERROR] 获取工具" << tool_number << "坐标范围参数失败，错误码: " << ret << std::endl;
        return -1;
    }
    std::cout << std::fixed << std::setprecision(4);
    std::cout << "[信息] 工具 " << tool_number << " 坐标范围参数:" << std::endl;
    std::cout << "  X轴范围: [" << range_param.min_range_x
              << ", " << range_param.max_range_x << "] mm" << std::endl;
    std::cout << "  Y轴范围: [" << range_param.min_range_y
              << ", " << range_param.max_range_y << "] mm" << std::endl;
    std::cout << "  Z轴范围: [" << range_param.min_range_z
              << ", " << range_param.max_range_z << "] mm" << std::endl;
    std::cout << "  工具握持方式: " << range_param.tool_hand_method << std::endl;