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

5. 新建并执行作业文件 ​

本期介绍如何用 Python SDK 在控制器上新建一个作业文件,写入动作指令并完成同步,然后执行、暂停、继续、停止,最后等待作业运行结束。

作业文件(Job)是控制器侧的指令序列载体。相比逐条下发运动指令,作业文件支持「下发一次、控制器按序执行」,并且可以被暂停、继续、停止,适合固定工艺流程的反复运行。

⚠️ 安全警告

  • 运行前确认机器人周围无人员和障碍物
  • 首次运行请使用低速
  • 建议先在仿真环境中验证,再上真机
  • 随时准备按下急停按钮

1、作业文件生命周期 ​

本 Demo 展示的完整链路为:

text
新建作业文件 → 打开作业文件 → 写入指令 → 同步到控制器
    → 设置运行次数 → 切换运行模式 → 启动
    → 暂停 → 继续 → 停止          (第一次生命周期)
    → 再次启动 → 等待运行结束      (第二次生命周期,跑到自然结束)

两次生命周期的区别值得注意:第一次是人为中断(暂停、继续、停止),第二次必须等待结果为 0 表示自然结束,才能验证作业文件内容本身没有问题。

2、配置作业参数 ​

python
# ===== 用户需要修改的部分 =====
ip = "192.168.3.239"
port = "6001"
job_name = "DemoJob"    # 作业文件昵称可根据需要修改

# ===== 重试与等待参数 =====
CONNECT_RETRY_COUNT = 5
WAIT_CONNECT_RETRY = 1
STATE_QUERY_RETRY_COUNT = 3
WAIT_STATE_QUERY_RETRY = 0.2
MODE_QUERY_RETRY_COUNT = 3
WAIT_MODE_QUERY_RETRY = 0.2
MODE_SWITCH_RETRY_COUNT = 3
WAIT_MODE_SWITCH_RETRY = 0.5
WAIT_STATE_TIMEOUT = 10
WAIT_STATE_INTERVAL = 0.2
WAIT_JOB_FINISH_TIMEOUT = 60
WAIT_JOB_START = 5
WAIT_JOB_PAUSE = 5
WAIT_JOB_CONTINUE = 3
JOB_CREATE_RETRY_COUNT = 3
JOB_OPEN_RETRY_COUNT = 3
JOB_WRITE_RETRY_COUNT = 3
JOB_SYNC_RETRY_COUNT = 3
JOB_RUN_TIMES_RETRY_COUNT = 3
JOB_CONTROL_RETRY_COUNT = 3
WAIT_JOB_CONTROL_RETRY = 0.5
JOB_TIMER_COUNT = 2
JOB_TIMER_VALUE = 8

JOB_TIMER_VALUE = 8 是写入作业文件的 Timer 指令时长(秒),用来让作业运行足够久,以便在运行过程中执行暂停/继续/停止操作。

3、新建、打开、写入、同步 ​

四个步骤依次进行,每一步都带有限次重试:

python
def open_job(fd):
    for i in range(JOB_OPEN_RETRY_COUNT):
        result = nrc_interface.job_open(fd, job_name)
        if result == 0:
            print("Job打开成功")
            return
        print(f"第{i+1}次打开Job失败,返回值:{result}")
        if i < JOB_OPEN_RETRY_COUNT - 1:
            time.sleep(WAIT_JOB_CONTROL_RETRY)
    raise Exception(f"连续{JOB_OPEN_RETRY_COUNT}次打开Job失败")
python
def write_job(fd):
    for i in range(JOB_TIMER_COUNT):
        check_result(
            nrc_interface.job_insert_timer_command(fd, i + 1, JOB_TIMER_VALUE), "写入Timer")
    print("Job写入完成")
python
def sync_job(fd):
    for i in range(JOB_SYNC_RETRY_COUNT):
        result = nrc_interface.job_sync_job_file(fd)
        if result == 0:
            print("Job同步成功")
            return
        print(f"第{i+1}次同步Job失败,返回值:{result}")
        if i < JOB_SYNC_RETRY_COUNT - 1:
            time.sleep(WAIT_JOB_CONTROL_RETRY)
    raise Exception(f"连续{JOB_SYNC_RETRY_COUNT}次同步Job失败")

四个接口的职责:

接口作用必要性
job_create在控制器新建作业文件必须,同名文件已存在时会返回失败
job_open打开作业文件进入可编辑状态必须,写入前必须先打开
job_insert_timer_command按行号插入 Timer 指令示例指令,可替换为运动指令
job_sync_job_file把编辑内容同步到控制器必须,未同步则运行时仍是旧内容

job_insert_timer_command 的第一个位置参数是行号(从 1 开始),第二个是 Timer 时长。写入多条指令时行号必须连续递增。

4、设置运行次数与运行模式 ​

python
def set_run_times(fd):
    for i in range(JOB_RUN_TIMES_RETRY_COUNT):
        result = nrc_interface.job_run_times(fd, JOB_RUN_TIMES)

        if result == 0:
            print(f"Job运行次数设置为{JOB_RUN_TIMES}次")
            return

        print(f"第{i+1}次设置运行次数失败,返回值:{result}")

        if i < JOB_RUN_TIMES_RETRY_COUNT - 1:
            time.sleep(WAIT_JOB_CONTROL_RETRY)

    raise Exception(f"连续{JOB_RUN_TIMES_RETRY_COUNT}次设置运行次数失败")

作业运行需要切换到运行模式(2)。切换后 Demo 会再次查询模式确认,而不是只信接口返回值:

python
def set_run_mode(socketFd):
    mode = get_mode(socketFd)
    print("当前模式:", mode)

    if mode == 2:
        print("当前已经是运行模式")
        return

    for i in range(MODE_SWITCH_RETRY_COUNT):
        result = nrc_interface.set_current_mode(socketFd, 2)

        if result == 0:
            time.sleep(WAIT_MODE_SWITCH_RETRY)
            current_mode = get_mode(socketFd)
            if current_mode == 2:
                print("已切换运行模式")
                return
            print(f"第{i+1}次切换后确认失败,当前模式:{current_mode}")
        else:
            print(f"切换运行模式失败,第{i+1}次,返回值:{result}")

        if i < MODE_SWITCH_RETRY_COUNT - 1:
            time.sleep(WAIT_MODE_SWITCH_RETRY)

    raise Exception(f"连续{MODE_SWITCH_RETRY_COUNT}次切换运行模式失败")

模式取值:0 示教模式、1 远程模式、2 运行模式。

5、暂停、继续、停止 ​

三个控制接口都需要「接口返回成功 + 状态查询确认」双重判据。原因是控制器偶发出现接口返回失败但实际已执行的情况:

python
def pause_job(fd):
    for i in range(JOB_CONTROL_RETRY_COUNT):
        result = nrc_interface.job_pause(fd)

        if result == 0:
            wait_state(fd, 1)
            print("====Job暂停====")
            return

        state = get_state(fd)
        if state == 1:
            print("Job暂停接口返回失败,但查询确认Job已经暂停")
            return

        print(f"第{i+1}次暂停Job失败,返回值:{result}")

        if i < JOB_CONTROL_RETRY_COUNT - 1:
            time.sleep(WAIT_JOB_CONTROL_RETRY)

    raise Exception(f"连续{JOB_CONTROL_RETRY_COUNT}次暂停Job失败")
python
def stop_job(fd):
    for i in range(JOB_CONTROL_RETRY_COUNT):
        result = nrc_interface.job_stop(fd)
        if result == 0:
            wait_stop(fd)
            return
        state = get_state(fd)
        if state == 0:
            print("Job停止接口返回失败,但查询确认Job已经停止")
            return
        print(f"第{i+1}次停止Job失败,返回值:{result}")
        if i < JOB_CONTROL_RETRY_COUNT - 1:
            time.sleep(WAIT_JOB_CONTROL_RETRY)
    raise Exception(f"连续{JOB_CONTROL_RETRY_COUNT}次停止Job失败")

continue_job 的结构与 pause_job 完全对称,目标状态为 2(运行)。运行状态取值:0 停止、1 暂停、2 运行。

6、状态查询与等待 ​

python
def get_state(fd):
    for i in range(STATE_QUERY_RETRY_COUNT):
        ret = nrc_interface.get_robot_running_state(fd, 0)
        if isinstance(ret, list) and len(ret) >= 2:
            if ret[0] == 0:
                return ret[1]
        print(f"获取机器人运行状态失败,第{i+1}次")
        time.sleep(WAIT_STATE_QUERY_RETRY)
    raise Exception(f"连续{STATE_QUERY_RETRY_COUNT}次获取机器人状态失败")


def wait_state(fd, target, timeout=WAIT_STATE_TIMEOUT):
    start = time.time()
    while time.time() - start < timeout:
        state = get_state(fd)
        print("机器人运动状态:", state)
        if state == target:
            return True
        time.sleep(WAIT_STATE_INTERVAL)
    raise TimeoutError(f"等待状态{target}超时")

isinstance(ret, list) and len(ret) >= 2 的写法用于屏蔽接口在异常时返回非列表的情况,避免 ret[0] 抛 TypeError 掩盖真实错误。

7、主流程 ​

python
def main():
    fd = None
    try:
        fd = connect_robot()

        create_job(fd)
        open_job(fd)
        write_job(fd)
        sync_job(fd)
        set_run_times(fd)
        set_run_mode(fd)

        run_job(fd)
        wait_state(fd, 2)
        time.sleep(WAIT_JOB_START)

        pause_job(fd)
        wait_state(fd, 1)
        time.sleep(WAIT_JOB_PAUSE)

        continue_job(fd)
        wait_state(fd, 2)
        time.sleep(WAIT_JOB_CONTINUE)

        stop_job(fd)
        wait_stop(fd)
        print("第一次生命周期完成")

        run_job(fd)
        wait_state(fd, 2)
        wait_finish(fd)

        print("Demo执行成功")
    ...

WAIT_JOB_START = 5、WAIT_JOB_PAUSE = 5、WAIT_JOB_CONTINUE = 3 是作业进入对应状态后的稳定等待时间。作业启动后状态可能短暂保持为 0,直接下发暂停会失败。

8、运行与预期输出 ​

bash
python 05_job_execute.py

预期输出依次出现:机器人连接成功、Job创建成功、Job打开成功、Job写入完成、Job同步成功、Job运行次数设置为1次、已切换运行模式、====Job启动====、机器人正在运行中...、====Job暂停====、====Job继续====、====Job已经停止====、第一次生命周期完成、Job自然运行完成,state:0、Demo执行成功、连接关闭。

9、常见问题 ​

job_create 一直失败

控制器上已存在同名 DemoJob。先删除控制器上的同名作业文件,或修改 job_name。

作业执行了但内容不对 / 仍是旧内容

漏调 job_sync_job_file。写入指令只是修改控制器内存中的编辑态,必须同步后才生效。

暂停接口返回非 0

作业可能尚未真正进入运行状态。确认 wait_state(fd, 2) 已通过后再暂停,并保留 WAIT_JOB_START 等待。

第二次运行一直等到超时

WAIT_JOB_FINISH_TIMEOUT = 60 需要大于「运行次数 × 单次 Timer 时长」。

下一步

需要让机器人按队列连续执行多段轨迹、且每段可在运行中追加时,参见 7. 追加队列模式(单机器人);作业文件的上传与备份参见 8. 上传下载文件。

完整可运行脚本见 devkit:04-上位机/Python/RTL-24.03(当前)/04-示例/基础示例/05-新建并执行作业文件/05_job_execute.py。

← 上一页:4. 断开连接 | 返回基础应用 | 下一步:6. 无作业文件运行 →