伺服状态设置接口

1. set_servo_state - 设置伺服就绪状态

方法： set_servo_state(socket_fd: int, state: int)

功能描述： 控制机器人各物理关节电机的抱闸释放与伺服使能状态。在机械臂上电后准备执行任何物理控制动作（如 move_joint、start_robot_jogging）之前，必须先下发使能指令（state=1）激活电机控制环路。当机器人长时间待机、发生紧急停止（E-Stop）或需要人工拖动示教时，可下发去使能指令（state=0）切断电机电流。

参数：

socket_fd：已连接的机械臂控制器句柄，整型格式（int）。
state：伺服动作目标控制状态，整型格式（int）。
- 1：伺服上电使能（Servo ON）。控制器会向驱动器下发磁场定向控制使能，并解锁物理刹车抱闸，使电机进入位置闭环锁死就绪状态。
- 0：伺服断电下电（Servo OFF）。控制器会立即接通抱闸并切断电机电流，机械臂物理关节失去主动保持力。

返回值：

int：状态码
- 0：执行成功。代表伺服状态成功切换。
- 非 0 整型值：执行失败。返回底层驱动器或控制器状态机抛出的硬性错误码（例如存在红色未清除报警时，上电会返回特定失败码）。
- -1：通信异常。常规控制通道句柄无效或触发底层通信中断。

使用示例：

Python

import time
import nrc_interface as nrc

# 1. 在执行任何动作测试前，硬性下发 1 启动物理电机上电使能
ret = nrc.set_servo_state(socket_fd, 1)

# 2. 校验伺服动作返回值
if ret == 0:
    print("成功: 机械臂各轴电机已合闸使能，可正常规划物理运动轨迹。")
    # 工业规范：伺服合闸后建议休眠 200ms 等待多轴抱闸彻底释放后再发运动指令
    time.sleep(0.2)
else:
    print(f"错误: 伺服使能失败，底层错误代码: {ret}。请检查急停按键是否释放或系统是否存在未复位报错。")

2. set_servo_poweron - 设置伺服上电状态(先使能)

方法： set_servo_poweron(socket_fd: int)

功能描述： 通过状态监控通道（6001 端口）向控制器发送复合上电原语。该接口首先将伺服状态机引导至就绪态，随后激活硬件继电器合闸上电，释放全轴电机的物理安全抱闸。

参数：

socket_fd：已连接的机械臂状态监控通道句柄，整型格式（int）。

返回值：

bool：执行结果布尔值
- True：上电成功（底层接口返回 0 且完成时序响应）或系统已经是上电状态（底层接口返回 -4）。
- False：上电失败。句柄无效、存在未复位的红色硬报错、系统处于急停（E-Stop）锁定状态、接口返回非预期错误码或触发通信异常。

使用示例：

Python

import time
import nrc_interface as nrc

# 1. 调用底层状态通道接口，下发使能状态 1
ret = nrc.set_servo_state(robotarm6001, 1)

# 2. 根据状态机返回码执行标准时序
if ret == 0:
    time.sleep(0.5)
    # 状态机引导成功后，切入物理合闸上电
    nrc.set_servo_poweron(robotarm6001)
    time.sleep(1.0)  # 硬性规定：必须留出 1 秒给抱闸和强电接触器物理响应
    print("成功: 机械臂已进入强电使能状态。")
elif ret == -4:
    print("提示: 机械臂伺服已经是上电就绪状态。")
else:
    print(f"错误: 伺服上电失败，底层状态码: {ret}。请检查安全回路。")

3. set_servo_poweroff - 设置伺服下电状态

方法： set_servo_poweroff(socket_fd: int)

功能描述： 通过状态监控通道（6001 端口）向控制器发送复合下电原语。该接口首先切断外部强电接触器/断路器的主供电回路，随后将驱动器状态机引导至去使能断电态，电机物理抱闸锁死。此操作常用于测试完毕退出程序、系统切换至安全待机或触发一般性安全停机。

参数：

socket_fd：已连接的机械臂状态监控通道句柄，整型格式（int）。

返回值：

bool：执行结果布尔值
- True：下电成功（底层接口返回 0 且完成时序响应）或系统本身就处于下电状态（底层接口返回 -4）。
- False：下电失败。句柄无效、底层状态机异常锁定、接口返回非预期错误码或触发通信异常。

使用示例：

Python

import nrc_interface as nrc

# 1. 调用底层状态通道接口，先下发断电原语切断强电
nrc.set_servo_poweroff(robotarm6001)

# 2. 随后切换伺服状态机为 0 (下电去使能)
ret = nrc.set_servo_state(robotarm6001, 0)

# 3. 根据状态机返回码执行标准判定
if ret == 0:
    print("成功: 机械臂主回路已安全断电，电机进入去使能锁死状态。")
elif ret == -4:
    print("提示: 机械臂系统当前已经是下电状态。")
else:
    print(f"错误: 伺服下电失败，底层状态码: {ret}。")

4. set_speed - 设置速度

方法： set_speed(socket_fd: int, speed: int)

功能描述： 修改机械臂控制器的全局再现/自动运行速度倍率。该指令会作为基准因子，直接等比例限制后续所有自动轨迹运动指令（如位置型直线、圆弧、关节运动）的实际物理运转速度。

参数：

socket_fd：已连接的机械臂常规指令通道句柄，整型格式（int）。
speed：目标速度百分比，整型格式（int）。通常有效取值范围为 1 ~ 100。

返回值：

bool：执行结果布尔值
- True：速度设置成功（底层接口返回 0）。
- False：设置失败。句柄无效、传入速度值越界（超出控制限额）、接口返回非 0 错误码或触发通信异常。

使用示例：

Python

import nrc_interface as nrc

# 1. 将全局自动化再现运行速度安全限制在 25%
target_speed = 25
ret = nrc.set_speed(socket_fd, target_speed)

# 2. 校验速度变更状态
if ret == 0:
    print(f"成功: 全局自动运动速度已成功锁死在 {target_speed}%, 后续轨迹将以此倍率安全运行。")
else:
    print("错误: 修改全局运行速度失败，请检查数值范围是否在 1-100 之间。")

5. get_speed - 获取速度

方法： get_speed(socket_fd: int, mode: int)

功能描述： 通过状态监控通道（6001 端口）实时读取控制器当前设定的全局再现/自动运行速度倍率。该数据反映了当前正在运行的自动化轨迹（或即将运行的轨迹）所遵循的速度上限因子。

参数：

socket_fd：已连接的机械臂状态监控通道句柄，整型格式（int）。
mode：预留控制代号，整型格式（int）。依据底层运动学算法规范，通常固定传入 0。

返回值：

int：速度倍率
- 1 ~ 100 的正整数：读取成功。代表当前控制器限制的全局速度百分比（%）。
- -1：读取失败。句柄无效、底层网络事件循环读取超时、底层未返回有效数据包或触发通信异常。

使用示例：

Python

import nrc_interface as nrc

# 1. 通过状态通道直接读取当前的物理全局速度倍率
ret = nrc.get_speed(robotarm6001, 0)

# 2. 对齐双模机制进行结果判定 (此处以 SDK 基础解包为例)
if isinstance(ret, (list, tuple)) and len(ret) >= 2 and ret[0] == 0:
    current_speed = int(ret[1])
    print(f"成功: 控制器当前全局再现速度为 {current_speed}%.")
elif isinstance(ret, int) and ret >= 0:
    print(f"成功: 控制器当前全局再现速度为 {ret}%.")
else:
    print("错误: 无法从状态通道获取有效的全局运行速度数据。")