模式与 IO 控制接口

1. set_current_mode - 设置机器人模式（切换示教模式和运动模式）

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

功能描述： 切换并配置机器人控制器当前的系统运行模式。

参数：

• socket_fd：已连接的机械臂控制器句柄，整型格式（int）。
• mode：准备切换的目标操作模式代号，整型格式（int），默认 0。
  • 0：示教模式（Teach / Manual）。允许进行手动点动（Jogging）、点位示教、单步微调。
  • 1：远程模式（Remote）。允许接收外部上位机、PLC等网络链路发送过来的远程控制及自动运行指令。
  • 2：运行模式 / 自动模式（Play / Auto）。用于执行控制器内部已加载的作业脚本或再现已保存的轨迹。

返回值：

• bool：执行结果布尔值
  • True：模式切换成功。底层接口返回 0，控制器成功完成系统操作模式的变更。
  • False：模式切换失败。句柄无效、模式代号参数越界、由于物理安全条件不满足（如硬件急停未松开或外部连锁信号缺失）导致控制器拒绝切换模式、接口返回非 0 错误码或触发通信异常。

使用示例：

import nrc_interface as nrc

# 1. 声明准备切换的系统模式（例如为了测试后续的点动控制，强制先切回 0: 示教模式）
target_mode = 0

# 2. 调用底层接口执行模式切换
ret = nrc.set_current_mode(socket_fd, target_mode)

# 3. 校验指令执行状态
if ret == 0:
    print(f"成功: 控制器已成功完成状态变更，当前处于 {target_mode} (示教模式)！")
    return True
else:
    print("错误: 切换机器人操作模式失败")
    return False

2. set_digital_output - 设置数字 IO 输出

方法： set_digital_io_output(socket_fd: int, port: int, value: int)

功能描述： 控制机器人控制器板载或扩展的数字量输出（DO）端口的状态。

参数：

• socket_fd：已连接的机械臂控制器句柄，整型格式（int）。
• port：准备配置的数字输出端口号，整型格式（int）。
• value：输出的目标电平状态值，整型格式（int）。
  • 1：输出高电平（信号导通 / ON）
  • 0：输出低电平（信号断开 / OFF）

返回值：

• bool：执行结果布尔值
  • True：高低电平设置成功。底层接口返回 0，控制器成功切换该物理硬件端口的状态。
  • False：设置失败。句柄无效、指定的 IO 端口号超出硬件配置范围、端口被系统锁定、接口返回非 0 错误码或触发通信异常。

使用示例：

import nrc_interface as nrc

# 1. 声明控制参数（例如控制 4 号输出端口打开）
valve_port = 4
state_on = 1

# 2. 调用底层接口执行 DO 控制
ret = nrc.set_digital_output(socket_fd, valve_port, state_on)

# 3. 校验指令执行状态
if ret == 0:
    print(f"成功: 控制器已成功将数字输出端口 {valve_port} 切换为高电平状态！")
    return True
else:
    print("错误: 设置数字 IO 输出状态失败")
    return False

3. get_digital_output - 获取所有数字 IO

方法： get_all_digital_io_outputs(socket_fd: int, out_vector: VectorInt)

功能描述： 一次性批量读取机器人控制器当前所有数字量输出（DO）端口的电平状态。

参数：

• socket_fd：已连接的机械臂控制器句柄，整型格式（int）。
• out_vector（底层输出参数）：专门用于接收底层整型数组的 C++ 动态向量容器（对应代码中的 nrc.VectorInt()）。由方法内部自动创建，并在调用前通过 push_back(0) 预先开辟与目标路数等长（默认 64 位）的内存缓冲区。接口执行成功后，所有端口的电平状态会顺序覆写至该容器内。

返回值：

• list：状态列表
  • [0, 1, 0, ...]：获取成功。返回包含各端口电平数值（1 代表高电平/ON，0 代表低电平/OFF）的标准 Python 列表。
  • []（空列表）：获取失败。句柄无效、底层驱动读取超时、接口返回非 0 错误码或触发通信异常。

使用示例：

import nrc_interface as nrc

# 1. 实例化官方定义的整型向量容器
out_vector = nrc.VectorInt()

# 2. 精准配置核心测试参数：为了防止底层指针越界，调用前必须显式分配 64 位缓冲空间
for _ in range(64):
    out_vector.push_back(0)

# 3. 调用底层批量读取接口，传入句柄与开辟好的缓冲容器
ret = nrc.get_digital_output(socket_fd, out_vector)

# 4. 校验接口状态码并转换为 Python 列表
if ret == 0:
    status_list = list(out_vector)
    print(f"成功: 控制器全部 64 路数字输出状态获取成功！第 1 路电平为: {status_list[0]}")
    return status_list
else:
    print("错误: 获取全部数字输出状态失败")
    return []

4. get_digital_input - 获取所有 IO 输入状态

方法： get_all_digital_io_inputs(socket_fd: int, in_vector: VectorInt)

功能描述： 一次性批量读取机器人控制器当前所有数字量输入（DI）端口的电平状态。

参数：

• socket_fd：已连接的机械臂控制器句柄，整型格式（int）。
• in_vector（底层输出参数）：专门用于接收底层整型数组的 C++ 动态向量容器（对应代码中的 nrc.VectorInt()）。由方法内部自动创建，并在调用前通过 push_back(0) 预先开辟与目标路数等长（默认 64 位）的内存缓冲区。接口执行成功后，所有端口的电平状态会顺序覆写至该容器内。

返回值：

• list：状态列表
  • [1, 0, 1, ...]：获取成功。返回包含各输入端口电平数值（1 代表高电平/有信号，0 代表低电平/无信号）的标准 Python 列表。
  • []（空列表）：获取失败。句柄无效、底层驱动读取超时、接口返回非 0 错误码或触发通信异常。

使用示例：

import nrc_interface as nrc

# 1. 实例化官方定义的整型向量容器
in_vector = nrc.VectorInt()

# 2. 显式分配 64 位缓冲空间，防止底层指针越界
for _ in range(64):
    in_vector.push_back(0)

# 3. 调用底层批量读取接口，传入句柄与开辟好的缓冲容器
ret = nrc.get_digital_input(socket_fd, in_vector)

# 4. 校验接口状态码并转换为 Python 列表
if ret == 0:
    status_list = list(in_vector)
    print(f"成功: 控制器全部 64 路数字输入状态获取成功！当前数据为: {status_list}")
else:
    print("错误: 获取全部数字输入状态失败")