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

1. 上电流程 ​

本期介绍如何使用 Python SDK 连接控制器,并根据当前伺服状态安全地完成清错、就绪和上电确认。

通过 SDK 控制机器人之前,需要先连接控制器,再根据当前伺服状态执行清错、切换就绪状态和伺服上电等操作。Python SDK 与 C++ SDK 的上电逻辑一致,区别在于 Python 侧接口直接返回 int 结果码,状态类接口返回 [结果码, 数据值] 列表。

伺服状态的含义如下:

  • 状态 0:伺服停止,需要先切换到就绪状态
  • 状态 1:伺服就绪,可以直接执行上电
  • 状态 2:伺服报警,需要先清除报警,再重新上电
  • 状态 3:伺服已经上电并进入运行状态

⚠️ 安全警告

伺服上电后,机器人将进入允许运动的状态。执行前必须确认:

  • 人员安全: 机器人工作空间内无人员或障碍物
  • 急停可用: 急停按钮处于可用状态,并在操作人员可触及范围内
  • 控制器状态: 控制器无未处理的安全报警,安全回路工作正常
  • 程序检查: 确认后续程序不会立即下发未经验证的运动指令
  • 现场配置: 控制器 IP 地址和 SDK 服务端口与实际配置一致

建议先在仿真环境中验证上电流程,确认状态切换符合预期后再连接真机。

机器人当前模式的含义如下:

  • 模式 0:示教模式,需要上电操作
  • 模式 1:远程模式
  • 模式 2:运行模式

1、配置连接参数与等待时间 ​

程序开头集中定义连接参数和各类等待时间,便于按现场环境统一调整。

python
# ===== 用户需要修改的部分 =====
ip   = "192.168.3.239"    # 控制器 IP
port = "6001"             # SDK 服务端口,需与控制器配置一致

# ===== 重试与等待参数 =====
CONNECT_RETRY_COUNT       = 5     # 连接失败后的最大重试次数
WAIT_CONNECT_RETRY        = 1     # 连接失败后的等待时间(秒)

MODE_SWITCH_RETRY_COUNT   = 3     # 切换示教模式的最大重试次数
WAIT_MODE_SWITCH_RETRY    = 0.5   # 模式切换失败后的重试间隔(秒)
MODE_RETRY_COUNT          = 3     # 获取机器人模式的最大重试次数
WAIT_MODE_RETRY           = 0.2   # 获取模式失败后的重试间隔(秒)
WAIT_MODE_SWITCH          = 1     # 模式切换完成后等待控制器更新状态(秒)

SERVO_STATUS_RETRY_COUNT  = 3     # 获取伺服状态的最大重试次数
WAIT_SERVO_STATUS_RETRY   = 0.2   # 获取伺服状态失败后的重试间隔(秒)
WAIT_SERVO_STABILIZE      = 1     # 发送上电指令前的状态稳定等待(秒)
WAIT_SERVO_READY          = 3     # 上电指令发出后等待伺服状态稳定(秒)
WAIT_SERVO_POWERON_CHECK  = 0.5   # 上电失败后重新查询前的等待(秒)
SERVO_POWERON_CHECK_COUNT = 2     # 判定上电成功所需的连续确认次数
SERVO_POWERON_RETRY_COUNT = 3     # 上电指令的最大重试次数
WAIT_SERVO_POWERON_RETRY  = 1     # 上电失败后的重试间隔(秒)

2、封装返回值检查函数 ​

Python SDK 的控制类接口直接返回 int 结果码,0 表示成功。把结果检查封装成函数,可以避免每个调用点都写一遍判断。

python
def check_result(result, action):
    """检查控制类接口返回值,非 0 直接抛出异常"""
    if result != 0:
        raise Exception(f"{action}失败,返回值:{result}")

3、连接控制器 ​

connect_robot(ip, port) 返回 socketFd,大于 0 即为有效连接句柄,后续所有接口都依赖这个句柄。

python
def connect_robot():
    for i in range(CONNECT_RETRY_COUNT):
        socketFd = nrc_interface.connect_robot(ip, port)
        if socketFd > 0:
            print("机器人连接成功")
            return socketFd
        print(f"第{i+1}次连接失败,等待重试")
        time.sleep(WAIT_CONNECT_RETRY)
    raise ConnectionError(f"连续{CONNECT_RETRY_COUNT}次连接机器人失败")

4、读取伺服状态 ​

伺服状态接口是查询类接口,返回 [结果码, 状态值] 列表。

python
def get_servo_status(socketFd):
    for i in range(SERVO_STATUS_RETRY_COUNT):
        status = nrc_interface.get_servo_state(socketFd, 0)
        # status[0]:接口执行结果,0 表示查询成功
        # status[1]:伺服状态,仅在 status[0]==0 时有效
        if status[0] == 0:
            return status[1]
        time.sleep(WAIT_SERVO_STATUS_RETRY)
    raise Exception(f"连续{SERVO_STATUS_RETRY_COUNT}次获取伺服状态失败")

5、按当前状态执行上电 ​

上电前先按状态 0/1/2/3 分流处理,再发送上电指令并连续确认实际状态。

python
def power_on(socketFd, state):
    if state == 0:                                    # 伺服停止
        print("当前伺服状态:", state, "(伺服停止)")
        check_result(nrc_interface.set_servo_state(socketFd, 1), "设置伺服就绪")

    elif state == 1:                                  # 伺服就绪
        print("当前伺服状态:", state, "(伺服就绪)")
        time.sleep(WAIT_SERVO_STABILIZE)

    elif state == 2:                                  # 伺服报警
        print("当前伺服状态:", state, "(伺服报警)")
        check_result(nrc_interface.clear_error(socketFd), "清除错误")
        check_result(nrc_interface.set_servo_state(socketFd, 1), "设置伺服就绪")

    elif state == 3:                                  # 已上电
        print("当前伺服状态:", state, "(伺服已经运行)")
        return

    else:
        raise Exception(f"未知伺服状态:{state}")

发送上电指令后,不能只凭返回值判定成功,还要连续确认实际状态已经进入运行态(状态 3):

python
    for i in range(SERVO_POWERON_RETRY_COUNT):
        ret = nrc_interface.set_servo_poweron(socketFd)
        if ret == 0:
            print("发送伺服上电指令")
            time.sleep(WAIT_SERVO_READY)
            # 上电指令发送成功后重新查询实际状态,
            # 确认控制器中的伺服状态确实已经进入上电状态
            poweron_check_count = 0
            for j in range(SERVO_POWERON_CHECK_COUNT):
                current_state = get_servo_status(socketFd)
                print(f"第{j+1}次确认伺服状态:{current_state}")
                if current_state == 3:
                    poweron_check_count += 1
                else:
                    poweron_check_count = 0
                    break
                if poweron_check_count >= SERVO_POWERON_CHECK_COUNT:
                    print("连续确认伺服已经上电,判定伺服上电成功")
                    return
            state = current_state

上电接口返回失败时同样要先重新查询实际状态,避免控制器已经上电却因返回值异常而重复下发指令:

python
        else:
            print(f"第{i+1}次伺服上电失败,返回值:{ret}")
            # 上电接口返回失败后先重新查询实际伺服状态,
            # 避免控制器实际上已经完成上电却因为接口返回异常而重复发送上电指令
            poweron_check_count = 0
            for j in range(SERVO_POWERON_CHECK_COUNT):
                time.sleep(WAIT_SERVO_POWERON_CHECK)
                current_state = get_servo_status(socketFd)
                if current_state == 3:
                    poweron_check_count += 1
                else:
                    poweron_check_count = 0
                    break
                if poweron_check_count >= SERVO_POWERON_CHECK_COUNT:
                    print("连续确认伺服已经上电,判定伺服上电成功")
                    return
            state = current_state

        # 根据重新查询到的实际状态决定下一步操作
        if state == 0:
            check_result(nrc_interface.set_servo_state(socketFd, 1), "重新设置伺服就绪")
        elif state == 2:
            check_result(nrc_interface.clear_error(socketFd), "重新清除伺服错误")
            check_result(nrc_interface.set_servo_state(socketFd, 1), "重新设置伺服就绪")
        elif state == 3:
            print("重新查询发现伺服已经上电")
            return
        time.sleep(WAIT_SERVO_POWERON_RETRY)
    raise Exception(f"连续{SERVO_POWERON_RETRY_COUNT}次伺服上电失败")

6、示教模式切换 ​

上电流程只在示教模式下需要。Demo 先查询当前模式,非示教模式时下发切换指令,并再次查询确认切换结果:

python
def get_current_mode(socketFd):
    for i in range(MODE_RETRY_COUNT):
        ret = nrc_interface.get_current_mode(socketFd, 0)
        if isinstance(ret, list):
            if ret[0] == 0:
                return ret[1]
        time.sleep(WAIT_MODE_RETRY)
    raise Exception(f"连续{MODE_RETRY_COUNT}次获取机器人模式失败")

def ensure_teach_mode(socketFd):
    mode = get_current_mode(socketFd)

    if mode == 0:
        print("当前机器人模式:", mode, "(示教模式)")
        return
    elif mode == 1:
        print("当前机器人模式:", mode, "(远程模式)")
    elif mode == 2:
        print("当前机器人模式:", mode, "(运行模式)")
    else:
        print("当前机器人模式:", mode, "(未知模式)")

    for i in range(MODE_SWITCH_RETRY_COUNT):
        result = nrc_interface.set_current_mode(socketFd, 0)
        if result != 0:
            print(f"第{i+1}次切换示教模式失败,返回值:{result}")
            if i < MODE_SWITCH_RETRY_COUNT - 1:
                time.sleep(MODE_SWITCH_RETRY)
                continue
            raise Exception(f"连续{MODE_SWITCH_RETRY_COUNT}次切换示教模式失败")

        # 接口返回成功只代表切换请求被接受,
        # 还需要等待控制器更新实际模式后再次查询确认
        time.sleep(WAIT_MODE_SWITCH)
        mode = get_current_mode(socketFd)
        if mode == 0:
            print("示教模式切换成功")
            return
        print(f"第{i+1}次切换后确认失败,当前机器人模式:{mode}")
        if i < MODE_SWITCH_RETRY_COUNT - 1:
            time.sleep(WAIT_MODE_SWITCH_RETRY)
    raise Exception(f"连续{MODE_SWITCH_RETRY_COUNT}次切换示教模式失败")

get_current_mode(socketFd, 0) 返回 [结果码, 模式值] 列表,因此 Demo 用 isinstance(ret, list) 先判断类型再取值;set_current_mode(socketFd, 0) 直接返回 int 结果码。

7、完整执行流程 ​

python
def main():
    socketFd = None
    try:
        socketFd = connect_robot()
        print("连接成功 socketFd =", socketFd)

        ensure_teach_mode(socketFd)
        state = get_servo_status(socketFd)
        power_on(socketFd, state)

        print("Demo执行成功")
    except KeyboardInterrupt:
        print("用户主动终止程序")
    except Exception as e:
        print("Demo执行异常:", e)
    finally:
        if socketFd:
            check_result(nrc_interface.disconnect_robot(socketFd), "断开连接")
            print("连接关闭")

完整可运行脚本见 devkit:04-上位机/Python/RTL-24.03(当前)/04-示例/基础示例/01-上电流程/01_power_on.py。

运行效果 ​

运行前状态Demo 行为预期输出
示教模式 + 伺服就绪直接发送上电指令并连续确认连续确认后判定成功
运行模式 + 伺服停止先切换到示教模式,再就绪并上电模式切换 + 上电成功
远程模式 + 伺服停止先切换到示教模式,再就绪并上电模式切换 + 上电成功

常见问题 ​

  • 连接失败: 检查控制器 IP、6001 端口是否可达,控制器 SDK 服务是否已开启
  • 上电一直失败: 查看 get_servo_state 返回值,状态 2 表示存在报警,需先 clear_error 排查报警源
  • 重复下发上电指令: Demo 在失败分支会先查询实际状态,若已上电则直接返回,不会重复下发

← 返回基础应用 | 下一步:伺服状态检测 →