博客：
四代控制器固件升级库使用说明

说明

适用对象：需要通过网络将升级包下发到睿尔曼四代控制器的 C++、Python 应用开发者及现场维护人员。

1. 功能概览

升级库将控制器固件升级接口封装为统一 API，完整流程如下：

将升级包上传到控制器；
等待控制器完成升级包解压，并获取可升级项目列表；
选择升级项目并启动升级；
轮询各项目升级进度；
升级完成后重启控制器，使新程序生效。

控制器与运行升级程序的计算机必须处于可互通网络中。

支持的升级包：

以 .realman 结尾的控制器版本、关节版本升级包；
末端控制器升级包，文件名必须为 tool.bin。

2. 发布包内容

目录/文件	说明
`rm_upgrade-windows-x64`	Windows x64 C++ 库、头文件和命令行程序
`rm_upgrade-linux-x86_64`	Linux x86_64 C++ 库、头文件和命令行程序
`rm_upgrade-linux-arm64`	Linux ARM64 C++ 库、头文件和命令行程序
`rm_upgrade_demo`	C++ 示例工程及 CMake 构建文件
`rm_upgrade_python`	Python ctypes 封装、Python 示例和对应平台动态库

C++ 库文件位于各平台包的 lib/ 目录，公共头文件为 include/upgrade_client.h。Windows 动态库为 upgrade_client.dll，Linux 动态库为 libupgrade_client.so；同时提供静态库。

3. 可执行程序使用说明

各平台包的 bin/ 目录提供 rm_upgrade（Windows 下为 rm_upgrade.exe）。运行帮助：

bash

# Linux
./bin/rm_upgrade --help

# Windows PowerShell
.\bin\rm_upgrade.exe --help

基本用法：

bash

# Linux
./bin/rm_upgrade 192.168.1.100 ./upgrade_pkg.realman

# Windows PowerShell
.\bin\rm_upgrade.exe 192.168.1.100 .\upgrade_pkg.realman

参数说明：

参数	默认值	说明
`<host>`	必填	控制器 IP 或主机名
`<package_file>`	必填	升级包路径
`--select <a,b,c>`	全部项目	仅升级指定项目名称，名称来自解压列表
`--extract-timeout <s>`	`120`	等待解压列表的最长时间（秒）
`--upgrade-timeout <s>`	`600`	等待升级完成的最长时间（秒）
`--poll <s>`	`2`	升级进度轮询间隔（秒）
`--clear-first`	关闭	上传前清除控制器上的升级状态
`--no-reboot`	关闭	升级完成后不自动重启控制器
`--connect-timeout <s>`	`10`	建立连接超时（秒）
`--transfer-timeout <s>`	`300`	读写超时（秒）

程序退出码：0 表示成功；1 参数错误；2 上传失败；3 获取解压列表失败；4 启动升级失败；5 连续进度查询失败；6 升级超时。

4. C++ 版本

4.1 集成要求

C++11 或更高版本；
引入 include/upgrade_client.h；
链接对应架构的 upgrade_client 库；
Linux 静态链接时还需链接线程库（Threads::Threads 或 -lpthread）；
Windows 使用 x64 库，动态链接时确保 upgrade_client.dll 位于程序目录或系统搜索路径中。

4.2 CMake 集成示例

cmake

add_executable(my_upgrade_app main.cpp)
target_include_directories(my_upgrade_app PRIVATE /path/to/include)
target_link_libraries(my_upgrade_app PRIVATE /path/to/libupgrade_client.a Threads::Threads)

Windows 可将库替换为 upgrade_client_static.lib 或 upgrade_client.lib，并按动态/静态链接方式配置运行时文件。

4.3 完整升级示例

cpp

#include "upgrade_client.h"
#include <iostream>

int main() {
    upgrade::UpgradeClient client("192.168.1.100");
    client.setTimeouts(10, 300);

    auto upload = client.uploadUpgradeFile("robot.realman");
    if (!upload) {
        std::cerr << "上传失败: " << upload.error << "\n";
        return 1;
    }

    upgrade::ExtractInfo extracted;
    if (!client.waitForExtractList(extracted, 120, 1000)) {
        std::cerr << "解压失败: " << client.lastError() << "\n";
        return 1;
    }

    for (auto& item : extracted.list) item.check = true;
    auto start = client.startUpgrade(extracted.list);
    if (!start) {
        std::cerr << "启动升级失败: " << start.error << "\n";
        return 1;
    }

    for (;;) {
        upgrade::RateInfo rate;
        if (!client.getUpgradeRate(rate)) {
            std::cerr << "查询进度失败: " << client.lastError() << "\n";
            continue;
        }
        bool done = !rate.list.empty();
        for (const auto& item : rate.list) {
            std::cout << item.name << ": " << item.rate << "%\n";
            if (item.rate < 100) done = false;
        }
        if (done) break;
    }

    auto reboot = client.sysReboot();
    if (!reboot) std::cerr << "重启失败: " << reboot.error << "\n";
    return 0;
}

4.4 主要 API

API	说明
`version()`	返回库版本字符串
`UpgradeClient(host)`	创建客户端，连接 `http://host:8090`
`setTimeouts(connect, transfer)`	设置连接、读写超时，单位为秒
`uploadUpgradeFile(path, stored_name)`	上传升级包
`getExtractList(out)`	查询一次解压状态
`waitForExtractList(out, timeout, poll_ms)`	轮询直到解压完成或超时
`startUpgrade(items)`	根据 `FileItem.check` 启动选定项目
`getUpgradeRate(out)`	获取各项目进度和状态
`clearUpgrade()`	清除控制器升级状态
`sysReboot()`	重启控制器
`lastError()`	获取布尔返回接口的传输/解析错误

CallResult 类型接口通过 ok 判断成功，并可查看 http_status、body、error；bool 类型接口返回 false 时通过 lastError() 获取错误原因。getExtractList() 返回成功但 ready == false 表示仍在解压，不是失败。

如需开启证书校验，可在首次请求前调用 setVerifyCertificate(true) 并配置 setCACertPath(path)；默认不校验证书，以兼容控制器常见的自签名证书环境。

5. Python 版本

5.1 环境与文件

Python 3.7 及以上；
直接使用 rm_upgrade_python/rm_upgrade.py 和 upgrade_client.py；
封装通过 ctypes 加载平台对应的 upgrade_capi 动态库，默认从 rm_upgrade_python/lib/<平台>/ 查找。

5.2 运行示例

bash

cd rm_upgrade_python
python rm_upgrade.py 192.168.1.100 ./robot.realman

常用参数：

bash

python rm_upgrade.py 192.168.1.100 ./robot.realman \
  --extract-timeout 180 --upgrade-timeout 900 --poll 3 --no-reboot

如果动态库不在默认目录，可显式指定：

bash

python rm_upgrade.py 192.168.1.100 ./robot.realman \
  --lib /path/to/upgrade_capi.so

Python 封装提供 upload()、wait_extract()、start_all()、get_rate()、clear()、reboot()、last_error() 和 version() 等方法。wait_extract() 返回解压项目字典列表，get_rate() 返回包含 name、rate 等字段的进度列表，失败时返回 None。

6. 从源码构建 C++ 示例

以下路径均以发布包解压后的根目录为基准。示例工程目录为：

text

<release-root>/rm_upgrade_demo-v1.0.2/rm_upgrade_demo/

其中：

相对路径	内容
`rm_upgrade_demo-v1.0.2/rm_upgrade_demo/app/main.cpp`	示例程序入口
`rm_upgrade_demo-v1.0.2/rm_upgrade_demo/CMakeLists.txt`	CMake 构建配置
`rm_upgrade_demo-v1.0.2/rm_upgrade_demo/lib/include/`	`upgrade_client.h` 头文件
`rm_upgrade_demo-v1.0.2/rm_upgrade_demo/lib/linux-x86_64/`	Linux x86_64 预编译库
`rm_upgrade_demo-v1.0.2/rm_upgrade_demo/lib/linux-arm64/`	Linux ARM64 预编译库
`rm_upgrade_demo-v1.0.2/rm_upgrade_demo/lib/windows-x64/`	Windows x64 预编译库

Linux x86_64

在 <release-root> 目录执行：

bash

cd rm_upgrade_demo-v1.0.2/rm_upgrade_demo
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
  -DRM_UPGRADE_BUILD=./lib/linux-x86_64
cmake --build build -j
./build/rm_upgrade_demo 192.168.1.100 ./upgrade_pkg.tar

生成文件：rm_upgrade_demo-v1.0.2/rm_upgrade_demo/build/rm_upgrade_demo。

Linux ARM64

将 -DRM_UPGRADE_BUILD 指向 ARM64 库目录，并根据实际交叉编译工具链增加 CMAKE_TOOLCHAIN_FILE：

bash

cd rm_upgrade_demo-v1.0.2/rm_upgrade_demo
cmake -S . -B build-arm64 \
  -DRM_UPGRADE_BUILD=./lib/linux-arm64 \
  -DCMAKE_TOOLCHAIN_FILE=./cmake/toolchains/aarch64-linux-gnu.cmake
cmake --build build-arm64 -j

生成文件：rm_upgrade_demo-v1.0.2/rm_upgrade_demo/build-arm64/rm_upgrade_demo。

Windows x64

在 PowerShell 中执行：

powershell

cd rm_upgrade_demo-v1.0.2/rm_upgrade_demo
cmake -S . -B build -A x64 `
  -DRM_UPGRADE_BUILD=./lib/windows-x64 `
cmake --build build --config Release
.\build\Release\rm_upgrade_demo.exe 192.168.1.100 .\upgrade_pkg.tar

如果使用动态库，运行时需将 lib/windows-x64/upgrade_client.dll 复制到 build/Release/，或加入系统 DLL 搜索路径。

示例工程必须链接与目标平台和 CPU 架构匹配的库，不能将 Linux x86_64 库链接到 ARM64 或 Windows 程序。

7. 注意事项与故障排查

升级前确认控制器 IP 可达，且升级过程中保持网络稳定。
升级包必须与目标控制器型号和版本匹配；末端控制器包文件名必须是 tool.bin。
不要在升级进度未达到 100% 前断电或重启控制器。
若上传成功但长时间没有解压列表，可增大 --extract-timeout，并检查控制器当前升级状态。
若进度查询偶发失败，应重试；连续失败时检查网络、控制器服务状态和超时参数。
升级完成后建议重启控制器；使用 --no-reboot 时需由现场流程另行重启。
Windows 动态链接失败时，确认 upgrade_client.dll 与可执行程序位于同一目录；Python 动态库加载失败时，确认 upgrade_capi.dll 与 Python 解释器架构一致。

8. 版本信息

库版本可通过 C++ 的 upgrade::version() 或 Python 的 client.version() 查询。

9. 开源代码库

该仓库提供四代控制器固件升级库配套示例源码，可直接参考对接升级API，快速实现二次开发、调试与功能验证。详情请参见： rm_controller_upgrade。

博客：四代控制器固件升级库使用说明 ​

1. 功能概览 ​

2. 发布包内容 ​

3. 可执行程序使用说明 ​

4. C++ 版本 ​

4.1 集成要求 ​

4.2 CMake 集成示例 ​

4.3 完整升级示例 ​

4.4 主要 API ​

5. Python 版本 ​

5.1 环境与文件 ​

5.2 运行示例 ​

6. 从源码构建 C++ 示例 ​

Linux x86_64 ​

Linux ARM64 ​

Windows x64 ​

7. 注意事项与故障排查 ​

8. 版本信息 ​

9. 开源代码库 ​

博客：
四代控制器固件升级库使用说明

1. 功能概览

2. 发布包内容

3. 可执行程序使用说明

4. C++ 版本

4.1 集成要求

4.2 CMake 集成示例

4.3 完整升级示例

4.4 主要 API

5. Python 版本

5.1 环境与文件

5.2 运行示例

6. 从源码构建 C++ 示例

Linux x86_64

Linux ARM64

Windows x64

7. 注意事项与故障排查

8. 版本信息

9. 开源代码库