Blog:

4th-Generation Controller Firmware Upgrade Library Usage

TIP

Intended for C++ and Python application developers and on-site maintenance personnel who need to deliver upgrade packages to a RealMan 4th-generation controller over the network.

1. Feature Overview

The upgrade library encapsulates the controller firmware upgrade interfaces into a unified API. The complete flow is as follows:

1. Upload the upgrade package to the controller;
2. Wait for the controller to finish extracting the upgrade package, and obtain the list of upgradable items;
3. Select the items to upgrade and start the upgrade;
4. Poll the upgrade progress of each item;
5. Restart the controller after the upgrade completes, so that the new program takes effect.

The controller and the computer running the upgrade program must be on a mutually reachable network.

Supported upgrade packages:

• Controller version and joint version upgrade packages ending with .realman;
• End controller upgrade packages, whose file name must be tool.bin.

2. Release Package Contents

Directory/File	Description
rm_upgrade-windows-x64	Windows x64 C++ library, headers, and command-line program
rm_upgrade-linux-x86_64	Linux x86_64 C++ library, headers, and command-line program
rm_upgrade-linux-arm64	Linux ARM64 C++ library, headers, and command-line program
rm_upgrade_demo	C++ sample project and CMake build files
rm_upgrade_python	Python ctypes wrapper, Python samples, and the dynamic library for the corresponding platform

The C++ library files are located in the lib/ directory of each platform package, and the public header file is include/upgrade_client.h. The Windows dynamic library is upgrade_client.dll, and the Linux dynamic library is libupgrade_client.so; static libraries are provided as well.

3. Executable Program Usage

The bin/ directory of each platform package provides rm_upgrade (rm_upgrade.exe on Windows). Run the help:

# Linux
./bin/rm_upgrade --help

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

Basic usage:

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

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

Parameter description:

Parameter	Default	Description
<host>	Required	Controller IP address or host name
<package_file>	Required	Path to the upgrade package
--select <a,b,c>	All items	Upgrade only the specified item names, which come from the extraction list
--extract-timeout <s>	120	Maximum time to wait for the extraction list (seconds)
--upgrade-timeout <s>	600	Maximum time to wait for the upgrade to complete (seconds)
--poll <s>	2	Upgrade progress polling interval (seconds)
--clear-first	Disabled	Clear the upgrade state on the controller before uploading
--no-reboot	Disabled	Do not automatically restart the controller after the upgrade completes
--connect-timeout <s>	10	Connection establishment timeout (seconds)
--transfer-timeout <s>	300	Read/write timeout (seconds)

Program exit codes: 0 indicates success; 1 parameter error; 2 upload failure; 3 failure to obtain the extraction list; 4 failure to start the upgrade; 5 consecutive progress query failures; 6 upgrade timeout.

4. C++ Version

4.1 Integration Requirements

• C++11 or later;
• Include include/upgrade_client.h;
• Link the upgrade_client library for the corresponding architecture;
• When statically linking on Linux, the thread library must also be linked (Threads::Threads or -lpthread);
• On Windows, use the x64 library. When dynamically linking, ensure that upgrade_client.dll is located in the program directory or in the system search path.

4.2 CMake Integration Example

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)

On Windows, the library can be replaced with upgrade_client_static.lib or upgrade_client.lib, and the runtime files are configured according to the dynamic or static linking method.

4.3 Complete Upgrade Example

#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 failed: " << upload.error << "\n";
        return 1;
    }

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

    for (auto& item : extracted.list) item.check = true;
    auto start = client.startUpgrade(extracted.list);
    if (!start) {
        std::cerr << "Failed to start the upgrade: " << start.error << "\n";
        return 1;
    }

    for (;;) {
        upgrade::RateInfo rate;
        if (!client.getUpgradeRate(rate)) {
            std::cerr << "Failed to query the progress: " << 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 failed: " << reboot.error << "\n";
    return 0;
}

4.4 Main APIs

API	Description
version()	Returns the library version string
UpgradeClient(host)	Creates a client connecting to http://host:8090
setTimeouts(connect, transfer)	Sets the connection and read/write timeouts, in seconds
uploadUpgradeFile(path, stored_name)	Uploads the upgrade package
getExtractList(out)	Queries the extraction state once
waitForExtractList(out, timeout, poll_ms)	Polls until the extraction completes or times out
startUpgrade(items)	Starts the selected items according to FileItem.check
getUpgradeRate(out)	Obtains the progress and status of each item
clearUpgrade()	Clears the upgrade state on the controller
sysReboot()	Restarts the controller
lastError()	Obtains the transmission/parsing error of the interfaces that return a bool

For interfaces of the CallResult type, use ok to determine success, and http_status, body, and error can be inspected; for interfaces of the bool type, call lastError() to get the error reason when false is returned. A successful getExtractList() with ready == false means the extraction is still in progress, not a failure.

To enable certificate verification, call setVerifyCertificate(true) before the first request and configure setCACertPath(path); by default the certificate is not verified, so as to work with the self-signed certificate environment typical of controllers.

5. Python Version

5.1 Environment and Files

• Python 3.7 or later;
• Use rm_upgrade_python/rm_upgrade.py and upgrade_client.py directly;
• The wrapper loads the upgrade_capi dynamic library for the corresponding platform through ctypes, and looks for it in rm_upgrade_python/lib/<platform>/ by default.

5.2 Running Example

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

Common parameters:

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

If the dynamic library is not in the default directory, specify it explicitly:

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

The Python wrapper provides methods such as upload(), wait_extract(), start_all(), get_rate(), clear(), reboot(), last_error(), and version(). wait_extract() returns a list of dictionaries describing the extracted items, and get_rate() returns a progress list containing fields such as name and rate, or None on failure.

6. Building the C++ Sample from Source

All the paths below are relative to the root directory after the release package is extracted. The sample project directory is:

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

Where:

Relative Path	Contents
rm_upgrade_demo-v1.0.2/rm_upgrade_demo/app/main.cpp	Sample program entry
rm_upgrade_demo-v1.0.2/rm_upgrade_demo/CMakeLists.txt	CMake build configuration
rm_upgrade_demo-v1.0.2/rm_upgrade_demo/lib/include/	The upgrade_client.h header
rm_upgrade_demo-v1.0.2/rm_upgrade_demo/lib/linux-x86_64/	Linux x86_64 prebuilt library
rm_upgrade_demo-v1.0.2/rm_upgrade_demo/lib/linux-arm64/	Linux ARM64 prebuilt library
rm_upgrade_demo-v1.0.2/rm_upgrade_demo/lib/windows-x64/	Windows x64 prebuilt library

Linux x86_64

Run the following commands in the <release-root> directory:

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

Generated file: rm_upgrade_demo-v1.0.2/rm_upgrade_demo/build/rm_upgrade_demo.

Linux ARM64

Point -DRM_UPGRADE_BUILD to the ARM64 library directory, and add CMAKE_TOOLCHAIN_FILE according to the actual cross-compilation toolchain:

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

Generated file: rm_upgrade_demo-v1.0.2/rm_upgrade_demo/build-arm64/rm_upgrade_demo.

Windows x64

Run the following commands in 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

When using the dynamic library, copy lib/windows-x64/upgrade_client.dll to build/Release/ at runtime, or add it to the system DLL search path.

The sample project must link the library matching the target platform and CPU architecture. The Linux x86_64 library must not be linked into an ARM64 or Windows program.

7. Notes and Troubleshooting

1. Before the upgrade, confirm that the controller IP is reachable and keep the network stable during the upgrade.
2. The upgrade package must match the target controller model and version; the end controller package file name must be tool.bin.
3. Do not power off or restart the controller before the upgrade progress reaches 100%.
4. If the upload succeeds but no extraction list appears for a long time, increase --extract-timeout and check the current upgrade state of the controller.
5. If progress queries fail intermittently, retry them; when consecutive failures occur, check the network, the controller service state, and the timeout parameters.
6. It is recommended to restart the controller after the upgrade completes; when --no-reboot is used, the on-site process must restart it separately.
7. When Windows dynamic linking fails, confirm that upgrade_client.dll is in the same directory as the executable; when the Python dynamic library fails to load, confirm that upgrade_capi.dll matches the architecture of the Python interpreter.

8. Version Information

The library version can be queried through upgrade::version() in C++ or client.version() in Python.

9. Open-Source Repository

The repository provides the sample source code that goes with the 4th-generation controller firmware upgrade library. You can refer to it directly to integrate with the upgrade API and quickly carry out secondary development, debugging, and functional verification. For details, see: rm_controller_upgrade.