5. 新建并执行作业文件
本期介绍如何用 Python SDK 在控制器上新建一个作业文件,写入动作指令并完成同步,然后执行、暂停、继续、停止,最后等待作业运行结束。
作业文件(Job)是控制器侧的指令序列载体。相比逐条下发运动指令,作业文件支持「下发一次、控制器按序执行」,并且可以被暂停、继续、停止,适合固定工艺流程的反复运行。
⚠️ 安全警告
- 运行前确认机器人周围无人员和障碍物
- 首次运行请使用低速
- 建议先在仿真环境中验证,再上真机
- 随时准备按下急停按钮
1、作业文件生命周期
本 Demo 展示的完整链路为:
新建作业文件 → 打开作业文件 → 写入指令 → 同步到控制器
→ 设置运行次数 → 切换运行模式 → 启动
→ 暂停 → 继续 → 停止 (第一次生命周期)
→ 再次启动 → 等待运行结束 (第二次生命周期,跑到自然结束)两次生命周期的区别值得注意:第一次是人为中断(暂停、继续、停止),第二次必须等待结果为 0 表示自然结束,才能验证作业文件内容本身没有问题。
2、配置作业参数
# ===== 用户需要修改的部分 =====
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 = 8JOB_TIMER_VALUE = 8 是写入作业文件的 Timer 指令时长(秒),用来让作业运行足够久,以便在运行过程中执行暂停/继续/停止操作。
3、新建、打开、写入、同步
四个步骤依次进行,每一步都带有限次重试:
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失败")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写入完成")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、设置运行次数与运行模式
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 会再次查询模式确认,而不是只信接口返回值:
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、暂停、继续、停止
三个控制接口都需要「接口返回成功 + 状态查询确认」双重判据。原因是控制器偶发出现接口返回失败但实际已执行的情况:
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失败")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、状态查询与等待
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、主流程
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、运行与预期输出
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。