Skip to content
🤖 AI 助手 / 自动化工具:先读 《AI 助手先读》 《Agent 开发指引》 《生成前信息采集清单》;机器可读入口 /llms.txt;技能包(SKILL)直链:SKILL.md

8. 上传下载文件 ​

本期介绍上位机与控制器之间的文件传输:上传作业文件、下载全部作业文件、下载控制器日志、备份控制器系统数据。

文件传输是现场运维的高频操作:换型时上传新作业文件,故障时下载日志,升级前备份系统配置。这些操作都通过 SDK 完成,不需要借助其他工具。

端口要求

文件上传下载除 SDK 服务端口(6001)外,还需要控制器 TCP 5000 端口可用。若只放通了 6001,连接能建立但传输会失败。

1、功能菜单 ​

Demo 采用菜单式交互,一个程序覆盖六类操作:

text
========== 文件传输 Demo ==========
1. 查询控制器作业文件
2. 上传单个作业文件
3. 上传作业文件目录
4. 下载全部作业文件
5. 下载控制器日志
6. 备份控制器系统数据/配置
0. 退出
python
def execute_operation(fd, option):
    if option == 1:
        return list_all_job_files(fd)
    elif option == 2:
        return upload_one_job_file(fd)
    elif option == 3:
        return upload_job_directory(fd)
    elif option == 4:
        return download_all_job_files(fd)
    elif option == 5:
        return download_controller_logs(fd)
    elif option == 6:
        return backup_controller_system(fd)
    return True

2、配置参数 ​

python
ip = "192.168.3.239"
port = "6001"

# ===== 文件传输参数 =====
# 下载Job时是否覆盖上位机已有的同名Job文件
cover_local_job_files = True

# ===== 控制器查询参数 =====
query_retry_interval = 0.5
query_max_failures = 3
job_refresh_timeout = 15
job_refresh_interval = 0.5

# ===== 日志下载参数 =====
minimum_log_count = 1
maximum_log_count = 100

# ===== 连接参数 =====
connect_retry_count = 5
connect_retry_interval = 1

cover_local_job_files = True 控制下载时是否覆盖本地同名文件。批量下载到已有工作目录前,建议先改为 False 试跑一次,确认文件命名规则。

3、查询作业文件列表(当前不支持) ​

python
def list_all_job_files(fd):
    print("当前Python SDK暂不支持直接读取Job列表")
    print(
        "原因:job_get_all_jobfile_name需要"
        "std::vector<std::vector<std::string>>&,"
        "但Python封装没有VectorVectorString"
    )
    return False

这是 Python 与 C++ 封装的能力差异:C++ 侧的 job_get_all_jobfile_name 使用 std::vector<std::vector<std::string>> 作输出参数,Python SWIG 封装中没有对应的 VectorVectorString 类型,因此无法按 C++ 方式调用。

替代做法:在示教器上查看作业文件列表,或按已知文件名直接上传/下载。

4、上传单个作业文件 ​

上传接口只接受 .JBR 作业文件,且会在本地先做校验:

python
def prompt_upload_file():
    while True:
        path = input_path("请输入本地 .JBR 作业文件完整路径(输入q取消):")
        if path is None:
            return None
        path = os.path.abspath(path)
        if not os.path.isfile(path):
            print(f"文件不存在:{path}")
            continue
        if not path.upper().endswith(".JBR"):
            print("job_upload_by_file仅用于.JBR作业文件")
            continue
        return path

上传使用 job_upload_by_file,上传后需调用 job_sync_job_file 让控制器刷新文件列表,job_refresh_timeout = 15 就是这个刷新等待的上限。

5、上传作业文件目录 ​

目录级上传使用 job_upload_by_directory,一次把整个目录下的作业文件送入控制器,适合换型时批量更新。

6、下载全部作业文件 ​

python
def download_all_job_files(fd):
    directory_path = prompt_download_directory()

    if directory_path is None:
        print("已取消下载作业文件")
        return True

    print(f"开始下载全部作业文件到:{directory_path}")

    check_result(
        nrc_interface.job_download_by_directory(
            fd, directory_path, cover_local_job_files
        ),
        "job_download_by_directory"
    )

    print("全部Job文件下载完成")

    return True

7、下载控制器日志 ​

python
def download_controller_logs(fd):
    while True:
        value = input(
            f"请输入下载日志数量({minimum_log_count}~{maximum_log_count}):"
        ).strip()

        try:
            count = int(value)
            if minimum_log_count <= count <= maximum_log_count:
                break
        except ValueError:
            pass

        print(
            f"输入无效,请输入{minimum_log_count}~"
            f"{maximum_log_count}之间的整数"
        )

    directory_path = prompt_download_directory()

    if directory_path is None:
        print("已取消下载日志文件")
        return True

    print(f"开始下载{count}个日志文件到:{directory_path}")
    print("时间较长,请耐心等待~")

    check_result(
        nrc_interface.log_download_by_quantity(
            fd, count, directory_path
        ),
        "log_download_by_quantity"
    )

    print("日志下载完成")

    return True

日志数量上限由 maximum_log_count = 100 控制。单次下载数量大、日志文件大时耗时较长,程序会先给出提示再执行。

8、备份控制器系统数据 ​

python
def backup_controller_system(fd):
    print(
        "系统备份会保存到控制器指定位置,"
        "请确保机器人处于空闲状态"
    )

    while True:
        answer = input(
            "是否继续执行系统备份(y/n):"
        ).strip().lower()

        if answer == "y":
            break

        if answer == "n":
            print("已取消系统备份")
            return True

        print("输入无效,请输入y或n")

    check_result(
        nrc_interface.backup_system(fd),
        "backup_system"
    )

    print("系统备份成功")

    return True

与其他项不同,backup_system 的产物保存在控制器侧,不在上位机。执行前须确认机器人空闲。

9、连接状态检查 ​

文件传输耗时较长,操作前需确认连接仍然有效:

python
def check_connection(fd):
    for i in range(query_max_failures):
        try:
            ret = nrc_interface.get_connection_status(fd)
            if ret == 0:
                return True
            print(f"检查控制器连接失败,第{i+1}次,返回值:{ret}")
        except Exception as e:
            print(f"检查控制器连接异常,第{i+1}次:{e}")
        time.sleep(query_retry_interval)
    return False

get_connection_status 返回 0 表示连接正常。与状态查询接口不同,它返回的是单个整数,不是列表。

10、主流程 ​

python
def main():
    fd = None

    try:
        fd = connect_robot()

        while True:
            option = show_menu()

            if option == 0:
                break

            if not check_connection(fd):
                raise Exception("控制器连接已经断开")

            try:
                success = execute_operation(fd, option)

                if success:
                    print("本次操作完成")
                else:
                    print("本次操作失败")

            except Exception as e:
                print(f"本次操作异常:{e}")

    except KeyboardInterrupt:
        print("用户主动终止程序")

    except Exception as e:
        print(f"Demo9执行异常:{e}")

    finally:
        if fd:
            try:
                nrc_interface.disconnect_robot(fd)
                print("连接关闭")
            except Exception as e:
                print(f"关闭连接异常:{e}")

内层 try 只包住单个功能,某项失败不会退出整个菜单循环,便于连续操作。

11、运行与预期输出 ​

bash
python 09_upload_download.py

启动后依次输出 机器人连接成功、提示:文件上传、下载还需要控制器 TCP 5000 端口可用,随后显示功能菜单。选择任一项后,操作结束输出 本次操作完成 或 本次操作失败;选择 0 或按 Ctrl+C 后输出 连接关闭。

12、常见问题 ​

连接成功但上传/下载失败

控制器 TCP 5000 端口未放通。这是本 Demo 最常见的失败原因,SDK 连接本身用的是 6001。

上传报「仅用于 .JBR 作业文件」

job_upload_by_file 只接受 .JBR。其他后缀的作业文件需要用目录上传,或先在示教器导出为 .JBR。

上传成功但控制器上看不到新作业

漏调 job_sync_job_file,或 job_refresh_timeout = 15 不够(文件较多时刷新更慢)。适当调大后重新查询。

想先看看控制器上有哪些作业文件

当前 Python SDK 不支持,见第 3 节。改用示教器查看,或按已知文件名操作。

相关章节

完整可运行脚本见 devkit:04-上位机/Python/RTL-24.03(当前)/04-示例/基础示例/08-上传下载文件/09_upload_download.py。

← 上一页:7. 追加队列模式(单机器人) | 返回基础应用