# mt_robot_framework

**Repository Path**: ikunCtrl/mt_robot_framework

## Basic Information

- **Project Name**: mt_robot_framework
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-15
- **Last Updated**: 2026-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mt_robot_framework

`mt_robot_framework` 是面向 Windows、MSVC 2022 x64 和 C++20 的多厂商机器人核心动态库。主要产物 `mt_robot_framework.dll` 通过统一的 `mt::robot::IRobot` 提供连接、原生状态、实时 TCP、程序管理、工程点位和程序变量 Session，并将厂家 SDK 类型限制在动态库内部。

仓库中的业务模块建立在核心公共 API 之上。业务是否支持某种机器人由业务自己的 Profile 决定；核心适配器可用，不代表该机器人自动支持所有业务。Qt GUI 仅用于接口联调和业务验证。

## 支持矩阵

| 能力 | 智流行 IMF / 钱江 | 珞石 Rokae / xCoreSDK |
|---|---|---|
| 核心适配器 | 支持 | 可选构建，支持六轴 `xMateRobot` |
| 原生状态与实时 TCP | 支持 | 支持 |
| 程序上传与启动 | 支持 | 支持 RL 工程导入与启动 |
| 正式停止程序 | 支持 | 不支持，SDK 没有等价接口 |
| 通用编号 IO 诊断 | 支持 | 不支持，SDK 使用命名工程变量 |
| 程序变量 Session | 编号寄存器、DI/DO、GVar、工程数值变量 | 命名 RL 工程变量 |
| 工程点位读取 | 支持 P 点 | 支持 `pN` 笛卡尔工程变量 |
| 手眼标定结果读取 | 支持，默认 `TaskLaserTrackCaliSetting_1` | 支持，默认 `laserhandeyedata1` |
| 多层多道业务 | 支持 | 未实现 Profile，返回业务不支持 |

准确能力以 `IRobot::supports()` 为准。IMF 的正式暂停和继续能力关闭，但保留厂家命令状态迁移诊断；Rokae 的能力边界见[珞石 Rokae 适配器](docs/适配器/珞石_Rokae.md)。

## 架构

```mermaid
flowchart LR
    App["上位机应用"]
    Business["业务模块<br/>Workflow / Profile / Renderer"]

    subgraph Core["mt_robot_framework.dll"]
        Api["公共 API<br/>IRobot / RobotProgramSession"]
        Adapters["内置适配器<br/>IMF / Rokae"]
    end

    Vendor["厂家运行库"]
    Robot["机器人控制器"]
    Gui["GUI 测试工具<br/>可选"]

    App --> Api
    App --> Business --> Api
    Api --> Adapters --> Vendor --> Robot
    Gui -.-> Api
    Gui -.-> Business
```

- `mt_robot_framework_shared` 生成主要运行库 `mt_robot_framework.dll`；适配器源码直接编译进该 DLL，不是独立插件。
- `imf_api.dll`、`xCoreSDK.dll` 是适配器使用的厂家运行库，不进入公共类型系统。
- 业务目标位于核心 DLL 外部，只依赖 `mt_robot_framework` 公共 API。
- Profile 将业务逻辑信号映射到具体厂家的程序变量，并同步生成程序正文、点位和 Manifest。
- `RobotState` 和 `RobotTelemetry` 只来自厂家 SDK 原生快照；扫描阶段、焊接段/层/道由业务 Session 解释。

完整组件关系、编译与运行时依赖、调用时序和扩展模型见[总体方案设计](docs/总体方案设计.md)。

## 核心能力

- 统一的机器人生命周期、能力查询和显式错误返回。
- 单次 SDK 快照生成机器人状态、TCP XYZ/RPY 和 Base→TCP 变换矩阵。
- 状态变化订阅和每轮成功采样的实时遥测订阅。
- 适配器自描述的 IO 来源、类型、读写权限和地址范围。
- 工程示教点批量读取及坐标系、构型、工具、工件和外部轴元数据。
- 按名称读取统一的 `TCP ← Camera` 手眼标定齐次变换，平移单位为毫米。
- 程序查询、上传、启动及厂家确实支持的控制能力。
- 类型化、白名单式、单活动实例 `RobotProgramSession`。
- UTF-8 公共字符串和保留厂家详情的 `RobotError`。

核心不提供任意控制器变量自动枚举，不使用业务变量推断机器人本体状态，也不把语义不同的厂家接口包装成同一种公共能力。

## 依赖与构建

| 依赖 | 用途 | 位置 |
|---|---|---|
| IMF SDK | IMF 适配器 | `third_party/imf` |
| MySQL Connector/C++ JDBC | IMF 手眼标定数据库读取 | `third_party/mysql-connector-c++-26.7.0-winx64`，官方二进制包被 Git 忽略 |
| Rokae xCoreSDK 0.5.0 | Rokae 适配器 | `third_party/librokae-v0.5.0.C130_40`，本地目录被 Git 忽略 |
| `mt_coordinate` | 位姿和坐标变换 | 仓库构建使用 `third_party/mt_coordinate`；安装包消费者通过独立 CMake package 提供 |
| spdlog | 适配器日志 | Git submodule |
| GoogleTest | 自动测试 | Git submodule，生产配置默认关闭、开发回归显式启用 |
| Qt 6.8.3 | 可选 GUI 测试工具 | 仅启用 GUI 时需要 |

核心动态库、静态辅助目标、适配器和无界面业务不依赖 Qt。

准备子模块和本地 Rokae SDK 后运行：

```bat
git submodule update --init --recursive
build.bat
```

`build.bat` 使用规定的 MSVC、CMake 和 Ninja 环境完成标准 Release、启用 Rokae 的无 Qt 构建、关闭 Rokae 的无 Qt 构建，并安装标准配置。具体命令和新增模块方法见[开发指南](docs/开发指南.md)。

常用选项：

| 选项 | 默认值 | 说明 |
|---|---:|---|
| `MT_ROBOT_FRAMEWORK_ENABLE_ROKAE` | `ON` | 是否编译 Rokae 适配器 |
| `MT_ROBOT_FRAMEWORK_BUILD_BUSINESS_MULTI_LAYER_MULTI_PASS` | `ON` | 是否编译多层多道业务 |
| `MT_ROBOT_FRAMEWORK_BUILD_GUI_TESTS` | `ON` | 是否编译 Qt GUI 测试工具 |
| `MT_ROBOT_FRAMEWORK_BUILD_TESTS` | `OFF` | 是否构建并注册自动测试 |
| `ROKAE_SDK_DIR` | 仓库内厂家包目录 | 可覆盖的 xCoreSDK 根目录 |

## 构建产物

默认安装根目录为 `install`。核心 SDK 与业务 SDK 是两个并列交付包：

```text
install/
├─ mt_robot_framework/
│  ├─ bin/                            核心 DLL、PDB 和厂家 runtime
│  ├─ include/mt_robot_framework/     核心公共头文件
│  ├─ lib/                            核心库和 CMake package
│  └─ tools/robot_gui_test/           可选通用 GUI 自包含目录
└─ businesses/
   └─ multi_layer_multi_pass/
      ├─ include/multi_layer_multi_pass/  业务公共头文件
      ├─ lib/                              mt_robot_businesses_mlmp.lib 和 CMake package
      └─ GUI/                              可选业务联调程序自包含目录
```

`mt_robot_framework` 目录只包含 `bin`、`include`、`lib` 和可选的 `tools`。它不内置 `mt_coordinate` 或业务 SDK；`mt_robot_frameworkConfig.cmake` 使用标准 `find_dependency(mt_coordinate CONFIG REQUIRED)`。多层多道 Config 只查找直接依赖 `mt_robot_framework`。依赖位置由使用方通过标准 CMake 搜索路径提供。

GUI 目录中的核心 DLL、厂家 runtime 和 Qt runtime 是工具运行副本；核心 `bin` 不包含 GUI EXE 或 Qt 文件。业务是静态库，因此业务包没有 `bin` 目录。

## 使用核心动态库

安装后通过 CMake package 链接主要动态库目标：

```cmake
find_package(mt_robot_framework CONFIG REQUIRED)
target_link_libraries(my_target PRIVATE mt_robot_framework::shared)
```

最小调用示例：

```cpp
#include <mt_robot_framework/mt_robot_framework.h>

mt::robot::RobotConnectionConfig config;
config.vendor = mt::robot::RobotVendor::IMF_QIANJIANG;
config.ip = "192.168.1.2";
config.port = 23333;
config.adapter_options["udp_port"] = "23334";
config.program_storage_directory = "robot_project";

auto created = mt::robot::createRobot(config);
if (!created.has_value()) {
    return;
}

std::unique_ptr<mt::robot::IRobot> robot = std::move(*created);
if (const auto connected = robot->connect(); !connected.has_value()) {
    return;
}

const auto telemetry = robot->getRobotTelemetry();
if (telemetry.has_value()) {
    // state、tcp_pose 和 base_to_tcp 来自同一次 SDK 采样。
}
```

公共 API 返回的 `std::string` 均为 UTF-8。调用可选操作前应查询 `supports()`，并检查每个 `RobotResult<T>`。

`mt_robot_framework::static` 作为辅助静态链接目标保留；使用时还需要满足对应厂家 SDK 的静态消费者链接要求。

## 使用多层多道业务

多层多道业务通过独立 CMake package 交付：

```cmake
find_package(mt_robot_businesses_mlmp CONFIG REQUIRED)
target_link_libraries(my_target PRIVATE mt_robot_businesses_mlmp)
```

业务 Config 会通过标准 `find_dependency(mt_robot_framework CONFIG REQUIRED)` 获得核心目标。业务公共 C++ API 位于：

```cpp
namespace mt::robot_framework::businesses::multi_layer_multi_pass
{
// ProgramPackage、ScanWorkflow、WeldExecutionSession 等。
}
```

## 文档索引

- [总体需求说明](docs/总体需求说明.md)
- [总体方案设计](docs/总体方案设计.md)
- [总体接口说明](docs/总体接口说明.md)
- [总体测试说明](docs/总体测试说明.md)
- [开发指南](docs/开发指南.md)
- [智流行 IMF 适配器](docs/适配器/智流行_IMF.md)
- [珞石 Rokae 适配器](docs/适配器/珞石_Rokae.md)
- [多层多道业务](docs/业务/多层多道/需求说明.md)
- [GUI 测试工具](docs/工具/GUI测试程序.md)