Drone Task SDK — 无人机任务组件开发平台

📦 v1.0.0 正式发布

# 将已有算法封装为
标准无人机任务组件

Drone Task SDK 提供参数解析、进度汇报、结果回调等基础设施， 让已有的 C++/ROS 算法零侵入地接入 Drone Task Manager。 通过 Web 上传 `.lldtp` 包即可动态扩展任务能力，支持多版本共存。

📖 快速开始 🚀 发布应用

## 核心能力

从算法开发到任务部署的全链路支持

🔧

### 参数解析 SDK

自动解析命令行 `--key value` 参数，支持 string/int/double/bool/path 类型安全读取，同时注入环境变量。

📡

### 双通道进度汇报

HTTP POST 回调为主通道，stdout JSON Lines 为 fallback。任一通道正常工作即可保证进度不丢失。

📦

### App 包动态扩展

编译好的任务打包为 `.lldtp`，通过 Web 上传即可注册为新任务。支持同一应用的多版本共存。

🔒

### 零算法侵入

核心算法库保持纯 ROS/纯算法依赖，SDK 仅在入口节点使用。已有项目只需新增一个 `_node.cpp`。

⚡

### 异常安全

`DRONE_TASK_MAIN` 宏自动捕获异常并上报错误，子任务崩溃不会导致管理器失稳。

🔁

### 锁文件检查

SDK 内置 `checkArmLock()` 检查 `/tmp/arm.lock`，防止任务在危险状态下启动。

## C++ SDK

仅需 30 行代码，将已有算法封装为标准任务

### 🎯 两种集成方式

方式一：继承 Task 基类（推荐）

C++

    #include <drone_task_sdk/task.hpp>
    #include <drone_task_sdk/main_macros.hpp>

    class MyTask : public drone_task::Task {
    public:
        void run(const drone_task::Params& params,
                 drone_task::Reporter& reporter) override {
            auto input = params.get_path("input");
            int epochs = params.get_int("epochs", 10);

            reporter.report(0, "任务启动");
            // ... 核心算法 ...
            reporter.report(50, "处理中...");
            // ...
            reporter.finish("{\"accuracy\":0.95}");
        }
    };

    DRONE_TASK_MAIN(MyTask)

方式二：手动控制（已有项目最小侵入）

C++

    #include <drone_task_sdk/params.hpp>
    #include <drone_task_sdk/reporter.hpp>

    int main(int argc, char** argv) {
        auto params_map = drone_task::parse_args(argc, argv);
        drone_task::Params params(params_map);
        drone_task::Reporter reporter;

        const char* url = std::getenv("DRONE_TASK_PROGRESS_URL");
        if (url) reporter.init(url);

        reporter.report(0, "开始");
        // ... 已有算法 ...
        reporter.finish("{\"result\":123}");
        return 0;
    }

### 📋 API 速查

- Params — `get_string` / `get_int` / `get_double` / `get_bool` / `get_path` / `has`
- Reporter — `report(percent, message, metadata_json)` 上报中间进度
- Reporter — `finish(result_json)` / `finish(result, files)` 上报最终结果
- Task — 继承后实现 `run(params, reporter)` 即可
- DRONE_TASK_MAIN — 宏自动生成 main，含异常捕获
- checkArmLock() — 检查 `/tmp/arm.lock` 是否存在
- parse_args — 解析 `--key value` 和 `--flag` 格式

### 🔌 CMake 集成

只需在 `package.xml` 添加依赖，CMake 自动处理头文件和链接：

CMake

    find_package(catkin REQUIRED COMPONENTS drone_task_sdk)
    catkin_package()
    add_executable(my_task src/my_task_node.cpp)
    target_link_libraries(my_task ${catkin_LIBRARIES})

## 发布应用

四步完成从编译到部署

1

#### 编译算法

在开发机上使用 catkin_make 编译任务可执行文件，确保链接 drone_task_sdk

2

#### 编写 manifest

创建 manifest.yaml，定义 app_id、version、command_template 和参数列表

3

#### 打包 .lldtp

将 manifest + bin/ + lib/ 打包为 tar.gz，重命名为 .lldtp 扩展名

4

#### 上传部署

在 Drone Task Manager Web 界面的 App 市场中拖放上传，即时生效

### 📦 打包脚本参考

Bash

    APP_ID="bag_analyzer"
    VERSION="1.0.0"
    mkdir -p ${APP_ID}/bin ${APP_ID}/lib

    # 复制可执行文件和依赖的 .so
    cp devel/lib/bag_analyzer/bag_analyzer ${APP_ID}/bin/
    cp devel/lib/libdrone_task_sdk.so     ${APP_ID}/lib/
    cp devel/lib/libbag_analyzer_lib.so   ${APP_ID}/lib/

    # 创建 manifest
    cat > ${APP_ID}/manifest.yaml << EOF
    version: "1"
    app_id: ${APP_ID}
    app_version: "${VERSION}"
    name: Bag 文件分析
    command_template: "{{app_dir}}/bin/bag_analyzer --bag {{bag_file}}"
    parameters:
      - name: bag_file
        type: path
        required: true
        source_dir: /data/bags
    EOF

    # 打包为 .lldtp
    cd ${APP_ID} && tar -czf ../${APP_ID}.lldtp manifest.yaml bin/ lib/

## 示例应用

开箱即用的参考实现，可直接编译部署

B

#### bag_analyzer v1.0.0

统计 ROS bag 文件中各 topic 的消息数量、类型和时长。依赖 rosbag。

🟢 C++ 📦 rosbag
P

#### pcd_info v1.0.0

解析 PCD 点云文件头部信息：点数、字段、格式、是否有 RGB/Intensity。零 PCL 依赖。

🟢 C++ 📦 无外部库
I

#### image_info v1.0.0

读取图像文件的尺寸、通道数、位深度和文件大小。使用 OpenCV 4.2。

🟢 C++ 📦 OpenCV
E

#### external_task v1.0.0

外部 catkin 工程引用 SDK 的最小示例。演示如何在独立包中接入 drone_task_sdk。

🟢 C++ 📦 模板

## REST API 概览

Drone Task Manager 提供完整的 REST + WebSocket API

方法 | 路径 | 说明
--- | --- | ---
GET | `/api/tasks/definitions` | 列出所有任务模板（内置 + App）
POST | `/api/tasks/instances` | 启动任务（自动注入 DRONE_TASK_PROGRESS_URL）
POST | `/api/tasks/instances/{id}/stop` | 停止任务（SIGTERM → SIGKILL fallback）
POST | `/api/apps/upload` | 上传 `.lldtp` App 包（multipart/form-data）
GET | `/api/apps` | 列出已安装的 App 包及其版本
DELETE | `/api/apps/{app_id}?version=x.x.x` | 卸载指定版本的 App
GET | `/api/files/choices` | 列出 path 参数的候选文件（基于 source_dir）
GET | `/api/system/info` | 获取 CPU / 内存 / 磁盘实时状态
WS | `/ws` | WebSocket 实时推送（状态 / 进度 / 日志 / 系统信息）

完整 API 文档见服务启动后的 `/docs` 页面（Swagger UI）