CS 机器人 Python SDK 快速使用手册

1. 简介

本手册着重说明 Elite Robots CS Python SDK 的环境配置、安装验证、机器人侧配置以及常用示例运行方法。

1.1 SDK 概述

Elite Robots CS Python SDK 基于 pybind11 与 CMake，对 Elite Robots CS C++ SDK 做 Python 绑定。开发者可以在 Python 中调用 Dashboard、Primary Port、RTSI、EliteDriver、运动学、位姿代数、控制器日志等接口，开发 CS 系列机械臂外部应用程序。

Python 包导入名为：

import elite_cs_sdk as cs

1.2 支持的操作系统

当前工程支持 Linux 与 Windows。Linux 下以 Ubuntu 为主要参考环境；Windows 下建议使用 Visual Studio、CMake 与 vcpkg 构建依赖。

1.3 支持的 Python 与机器人软件版本

Python：python3 >= 3.6
CS Controller：
- 2.13.x：需要 >= 2.13.4
- 2.14.x：需要 >= 2.14.2

如果机器人控制软件版本低于上述要求，建议先升级机器人控制软件。

1.4 Python SDK 与底层 C++ SDK

本 Python SDK 需要指定一个本地 Elite Robots CS C++ SDK 仓库路径作为底层源码依赖，构建时通过 ELITE_CS_SDK_REPO 传入：

-DELITE_CS_SDK_REPO=<Elite_Robots_CS_SDK 本地路径>

可以到 GitHub 仓库选择需要的 SDK tag：

2. 环境准备

2.1 Ubuntu 编译安装

2.1.1 安装依赖

sudo apt update

# 基础工具
sudo apt install -y build-essential cmake git python3 python3-pip

# SDK 依赖
sudo apt install -y libboost-all-dev libssh-dev

# 运动学插件依赖。开启 ELITE_COMPILE_KIN_PLUGIN=ON 时建议安装
sudo apt install -y libeigen3-dev liborocos-kdl-dev

# Python 构建依赖。请安装到实际用于构建的 Python 环境中
python3 -m pip install setuptools wheel build pybind11 pybind11_stubgen

如果需要运行 examples/example_servoj_plan.py，还需要安装 numpy：

python3 -m pip install numpy

2.1.2 下载代码

git clone https://gitee.com/elite-robots/Elite_Robots_CS_SDK_Python
git clone <Elite_Robots_CS_SDK_Python 仓库地址>

如果使用压缩包源码，请分别解压 C++ SDK 和 Python SDK，并记录 C++ SDK 的本地路径。

2.1.3 构建 wheel 并安装

进入 Python SDK 根目录，执行：

cmake -S . -B build \
    -DELITE_CS_SDK_REPO=<Elite_Robots_CS_SDK 本地路径> \
    -DELITE_COMPILE_KIN_PLUGIN=ON \
    -DELITE_COMPILE_POSE_ALG_PLUGIN=ON

cmake --build build --target python_wheel

python3 -m pip install --force-reinstall dist/elite_cs_sdk-*.whl

如果网络较差，或需要离线构建，可提前准备 pybind11 源码并使用：

cmake -S . -B build \
    -DELITE_CS_SDK_REPO=<Elite_Robots_CS_SDK 本地路径> \
    -DFETCHCONTENT_SOURCE_DIR_PYBIND11=<本地 pybind11 源码目录> \
    -DFETCHCONTENT_UPDATES_DISCONNECTED=ON \
    -DELITE_COMPILE_KIN_PLUGIN=ON \
    -DELITE_COMPILE_POSE_ALG_PLUGIN=ON \
    -DPython3_EXECUTABLE=$(which python3)

cmake --build build --target python_wheel

python3 -m pip install --force-reinstall dist/elite_cs_sdk-*.whl

2.1.4 验证安装

安装完成后执行：

python3 - <<'PY'
import os
import elite_cs_sdk as cs

print("elite_cs_sdk:", os.path.dirname(cs.__file__))
print("SDK_VERSION_INFO:", cs.SDK_VERSION_INFO)
PY

如果能正常导入并打印包路径，说明 Python 包已安装成功。

2.2 Windows 编译安装

2.2.1 安装工具

需要安装：

Visual Studio，并勾选“使用 C++ 的桌面开发”
CMake
Git
Python 3
vcpkg

2.2.2 使用 vcpkg 安装依赖

在 Windows 终端中执行：

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat

.\vcpkg install boost-asio
.\vcpkg install libssh
.\vcpkg install orocos-kdl
.\vcpkg install eigen3
.\vcpkg integrate install

如果已经通过 vcpkg 安装了完整 boost，建议移除 vcpkg 的 Python 相关包，避免构建时优先使用 vcpkg 自带 Python：

.\vcpkg remove python3 boost-parameter-python boost-python
.\vcpkg integrate install

安装 Python 构建依赖：

python -m pip install setuptools wheel build pybind11 pybind11_stubgen

2.2.3 构建 wheel 并安装

Windows + vcpkg 构建时必须指定 CMAKE_TOOLCHAIN_FILE：

进入 Python SDK 根目录，执行：

cmake -S . -B build ^
    -DELITE_CS_SDK_REPO=<Elite_Robots_CS_SDK 本地路径> ^
    -DELITE_COMPILE_KIN_PLUGIN=ON ^
    -DELITE_COMPILE_POSE_ALG_PLUGIN=ON ^
    -DCMAKE_TOOLCHAIN_FILE=<your vcpkg path>/scripts/buildsystems/vcpkg.cmake

cmake --build build --config Release --target python_wheel

python -m pip install --force-reinstall dist/elite_cs_sdk-*.whl

2.3 只验证扩展编译

如果只想验证 pybind 扩展是否能编译，不打包 wheel，可以执行：

cmake --build build --target elite_cs_sdk_python

2.4 常用目录说明

安装 wheel 后，Python 包中会包含：

elite_cs_sdk_python.*：Python 扩展模块
external_control.script：EliteDriver 外部控制脚本模板
*.pyi：类型提示文件
可选插件库：运动学插件、位姿代数插件

在 Python 中可以这样获取 external_control.script 的路径：

import os
import time
import elite_cs_sdk as cs

script_path = os.path.join(os.path.dirname(cs.__file__), "external_control.script")
print(script_path)

3. 机器人配置

3.1 网络配置

3.1.1 CS 标准系列控制柜

CS 标准系列控制柜需要注意 FB1 与 FB2 两个网口：

Dashboard 功能运行在 FB1 处理器上，Dashboard 示例应连接 FB1 IP。
Primary Port、RTSI、EliteDriver 外部控制运行在 FB2 处理器上，运动控制和实时数据示例应连接 FB2 IP。

因此，通常需要将运行 Python SDK 的电脑、FB1、FB2 接入同一个局域网，并分别设置好 IP。

在 2.14.3 版本后，使用 SDK 的 headless 模式可以只连接 FB2 网口，但如果需要 Dashboard 连接，仍需确保 Dashboard 所在网络可达。

3.1.2 CS_X 系列控制柜

CS_X 系列控制柜只有一个网口，连接该网口并设置好 IP 即可。

3.2 设置远程控制模式

点击示教器右上角菜单，选择设置：

启用或禁用远程控制模式，然后点击左下角退出按钮：

如果启用了远程控制模式，需要在界面右侧切换到“远程控制”：

CS 系列机器人如果远程控制模式为禁用状态，会处于“混合模式”，既可以接收外部控制，也可以接收示教器本地控制。因此，远程控制模式可根据现场使用习惯选择启用或禁用。

3.3 测试网络连接

推荐优先使用 Python SDK 自带的连接测试示例。

3.3.1 使用 Python 示例测试

在 Python SDK 根目录执行：

python3 examples/connect_robot_test.py --ip <机器人 Primary/FB2 IP>

如果本机有多个网卡，或者自动获取的本机 IP 不正确，可以显式指定本机 IP：

python3 examples/connect_robot_test.py \
    --ip <机器人 Primary/FB2 IP> \
    --local_ip <本机与机器人同网段 IP> \
    --server_port 50002

此示例会完成以下动作：

在本机启动一个 TCP server。
连接机器人 Primary Port，默认端口为 30001。
通过 PrimaryClientInterface.sendScript() 向机器人下发脚本。
让机器人通过 socket_open() 回连本机 TCP server。
收到 hello 字符串后打印成功日志。

如果此示例能跑通，说明机器人到 SDK 所在电脑的回连链路基本正常。

3.3.2 使用 ping 或 ssh 辅助检查

Linux 下查看本机 IP：

ip addr

也可以使用：

ifconfig

如果系统提示没有 ifconfig，可安装：

sudo apt install net-tools

Windows 下查看本机 IP：

ipconfig

检查电脑是否能访问机器人：

ping <机器人 IP>

如果需要从机器人侧检查是否能访问电脑，可通过 ssh 登录机器人系统。注意替换为机器人 IP，CS 标准系列控制柜通常使用 FB2 IP：

ssh root@<机器人 IP>

密码通常为：

elibot

登录后执行：

ping <本机与机器人同网段 IP>

3.4 常见网络问题

使用虚拟机时，虚拟机网卡需要桥接到与机器人相连的物理网卡。
CS 标准系列控制柜运行 Primary、RTSI、EliteDriver 示例时，应确认 FB2 网口已连接。
IP 地址需要位于同一网段，且不能冲突。
建议关闭 VPN 后测试。
如果本机 TCP server 端口被占用，可以更换端口；机器人脚本中对应端口也要一起更换。
如果机器人提示 socket_open、socket_read_binary_integer 或某个 socket 未连接，通常是机器人无法回连 SDK 所在电脑，需要优先检查本机 IP、防火墙、网卡、交换机、端口占用和 FB2 连接。
如果上述配置确认无误但仍无法连接，可以重启控制柜后再测试。

4. Python SDK 使用

4.1 Dashboard 快速示例

Dashboard 提供机器人上电、下电、释放抱闸、设置速度比例、弹窗、查询机器人模式等接口。

CS 标准系列控制柜请连接 Dashboard/FB1 IP；CS_X 系列控制柜使用机器人 IP。

4.1.1 运行仓库示例

python3 examples/example_dashboard_client.py --ip <机器人 Dashboard/FB1 IP>

该示例会调用：

DashboardClientInterface.connect(ip, port)
version()
setSpeedScaling(30)
speedScaling()
robotMode()
safetyMode()
popup("-s", "Hello from Python SDK!")
powerOn()
brakeRelease()
powerOff()
disconnect()

为了更直观地观察效果，运行前可以将机械臂下电：

4.1.2 最小 Dashboard 代码

复制下面代码到 dashboard_example.py：

#!/usr/bin/env python3
import argparse
import sys
import elite_cs_sdk as cs


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--ip", required=True, help="机器人 Dashboard/FB1 IP")
    parser.add_argument("--port", type=int, default=29999)
    args = parser.parse_args()

    dashboard = cs.DashboardClientInterface()

    if not dashboard.connect(args.ip, args.port):
        print("Could not connect to dashboard", file=sys.stderr)
        return 1

    print("Dashboard version:", dashboard.version())

    if not dashboard.powerOn():
        print("Power on failed", file=sys.stderr)
        return 1

    if not dashboard.brakeRelease():
        print("Brake release failed", file=sys.stderr)
        return 1

    dashboard.disconnect()
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

运行：

python3 dashboard_example.py --ip <机器人 Dashboard/FB1 IP>

如果执行成功，机器人会完成上电并释放抱闸。

4.2 Primary Port 示例

Primary Port 默认端口为 30001，可用于发送机器人脚本、上电、下电、释放抱闸、暂停任务、停止任务、获取 Primary 数据包等。

最小脚本发送示例：

import elite_cs_sdk as cs

robot_ip = "<机器人 Primary/FB2 IP>"

primary = cs.PrimaryClientInterface()
if not primary.connect(robot_ip):
    raise RuntimeError("connect primary failed")

script = """def hello_from_python():
    textmsg("Hello from Python SDK")
end
"""

if not primary.sendScript(script):
    raise RuntimeError("send script failed")

primary.disconnect()

也可以直接运行连接测试示例：

python3 examples/connect_robot_test.py --ip <机器人 Primary/FB2 IP>

4.3 RTSI 状态读取与输入示例

RTSI 默认端口为 30004，常用于获取机器人实时状态、设置速度比例、设置 IO 等。

运行仓库示例：

python3 examples/example_rtsi_client.py --ip <机器人 RTSI/FB2 IP>

该示例会：

创建 RtsiClientInterface()。
调用 connect(ip, 30004)。
调用 negotiateProtocolVersion()。
调用 getControllerVersion()。
使用 setupOutputRecipe() 订阅 actual_joint_positions、target_joint_positions、target_speed_fraction。
调用 start() 开始同步。
调用 receiveData() 获取数据。
暂停同步后使用 setupInputRecipe() 与 send() 设置速度比例。
调用 pause() 与 disconnect() 退出。

最小状态读取代码：

import elite_cs_sdk as cs

robot_ip = "<机器人 RTSI/FB2 IP>"

client = cs.RtsiClientInterface()
client.connect(robot_ip, 30004)

if not client.negotiateProtocolVersion():
    raise RuntimeError("RTSI protocol negotiation failed")

recipe = client.setupOutputRecipe(
    ["actual_joint_positions", "target_joint_positions", "target_speed_fraction"],
    125.0,
)

if not client.start():
    raise RuntimeError("RTSI start failed")

recipes = [recipe]
client.receiveData(recipes, read_newest=True)

sample = recipes[0]
for name in sample.getRecipe():
    print(name, "=", sample.getValue(name))

client.pause()
client.disconnect()

4.4 EliteDriver 外部控制示例

EliteDriver 用于和机器人建立外部控制通道，并向机器人发送运动控制数据，例如：

writeServoj(pos, timeout_ms, cartesian=False, queue_mode=False)
writeSpeedl(vel, timeout_ms)
writeIdle(timeout_ms)
writeFreedrive(action, timeout_ms)
writeTrajectoryPoint(...)
writeTrajectoryControlAction(...)
stopControl(wait_ms=10000)

运行运动示例前，请确认：

机器人工作空间安全，无人员或障碍物处于危险区域。
急停、使能、抱闸状态正常。
本机 IP 与机器人控制网口网络互通。
external_control.script 已随 wheel 安装到 elite_cs_sdk 包目录。

4.4.1 运行 speedl 示例

example_speedl.py 会让 TCP 沿 Z 方向先向下运动，再向上运动：

python3 examples/example_speedl.py \
    --ip <机器人 Primary/FB2 IP> \
    --local_ip <本机与机器人同网段 IP> \
    --use_headless_mode true

如果本机只有一个与机器人互通的网卡，可以尝试不传 --local_ip，让 SDK 自动获取：

python3 examples/example_speedl.py \
    --ip <机器人 Primary/FB2 IP> \
    --use_headless_mode true

示例中的关键配置如下：

import os
import elite_cs_sdk as cs

config = cs.EliteDriverConfig()
config.robot_ip = "<机器人 Primary/FB2 IP>"
config.local_ip = "<本机与机器人同网段 IP>"
config.servoj_time = 0.004
config.servoj_gain = 2000
config.servoj_lookahead_time = 0.3
config.script_file_path = os.path.join(os.path.dirname(cs.__file__), "external_control.script")
config.headless_mode = True

driver = cs.EliteDriver(config)
primary = driver.primaryPort()

primary.powerOn()
primary.brakeRelease()

if not driver.isRobotConnected():
    driver.sendExternalControlScript()

while not driver.isRobotConnected():
    time.sleep(0.01)

driver.writeSpeedl([0, 0, -0.02, 0, 0, 0], -1)
driver.stopControl()

headless_mode=True 时，示例会通过 Primary Port 发送外部控制脚本；headless_mode=False 时，需要在机器人侧启动 External Control 任务。

4.4.2 运行 servoj 规划示例

example_servoj_plan.py 使用 RTSI 读取当前关节位置，再通过 writeServoj() 控制第 6 轴正反向运动。运行前需要安装 numpy。

python3 -m pip install numpy

python3 examples/example_servoj_plan.py \
    --ip <机器人 Primary/RTSI/FB2 IP> \
    --local_ip <本机与机器人同网段 IP> \
    --use_headless_mode true \
    --max_speed 2.0 \
    --max_acc 2.0

4.4.3 Freedrive 示例

python3 examples/example_freedrive.py \
    --ip <机器人 Primary/FB2 IP> \
    --local_ip <本机与机器人同网段 IP> \
    --use_headless_mode true

启动后会进入 Freedrive 模式，按 Ctrl+C 退出，示例会发送 FREEDRIVE_END 并调用 stopControl()。

4.5 运动控制常见异常

示教器提示 socket_read_binary_integer 未连接某个 socket。
通常是机器人无法连接 Python SDK 在本机开启的 TCP server。请检查本机 IP、端口占用、防火墙、网卡、虚拟机桥接、FB2 连接以及 VPN。

程序抛出端口占用异常。

EliteDriver 会使用多个本地端口。可以检查常用端口占用：

netstat -ano | grep 50001
netstat -ano | grep 50002
netstat -ano | grep 50003
netstat -ano | grep 50004

Windows PowerShell 可使用：

netstat -ano | findstr 50001
netstat -ano | findstr 50002
netstat -ano | findstr 50003
netstat -ano | findstr 50004

机器人运动过程中提示 socket 超时。
可能是控制循环发送指令不及时、电脑负载过高、网络不稳定或网线松动。实时控制示例建议使用有线网络，并避免在虚拟机或高负载环境下运行。
机器人提示目标位姿不可达或奇异。
请先用示教器将机器人移动到合理、安全的起始位姿，再降低速度或缩小目标位移。

5. API 与示例索引

5.1 API 文档

中文 API 文档入口：

doc/API/API/cn/API.cn.md

常用模块：

EliteDriver：doc/API/API/cn/EliteDriver.cn.md
EliteDriverConfig：doc/API/API/cn/EliteDriverConfig.cn.md
PrimaryPort：doc/API/API/cn/PrimaryPort.cn.md
RTSI：doc/API/API/cn/RTSI.cn.md
Dashboard：doc/API/API/cn/Dashboard.cn.md
Kinematics：doc/API/API/cn/Kinematics.cn.md
PoseAlgebra：doc/API/API/cn/PoseAlgebra.cn.md

5.2 示例文件

仓库中的常用示例：

examples/example_dashboard_client.py：Dashboard 上电、释放抱闸、查询状态。
examples/connect_robot_test.py：Primary Port 下发脚本并测试机器人回连。
examples/example_rtsi_client.py：RTSI 配方订阅、数据读取、速度比例输入。
examples/example_speedl.py：EliteDriver TCP 速度控制。
examples/example_servoj_plan.py：EliteDriver 关节伺服控制。
examples/example_freedrive.py：Freedrive 控制。
examples/example_trajectory.py：轨迹运动控制。
examples/example_kinematics.py：运动学接口。
examples/example_pose_algebra.py：位姿代数接口。
examples/example_serial.py：串口通信接口。

6. 快速排查清单

Python 包是否能导入：python3 -c "import elite_cs_sdk as cs; print(cs.__file__)"
机器人软件版本是否满足要求。
CS 标准控制柜是否区分了 FB1 和 FB2 的 IP。
Dashboard 示例是否连接 Dashboard/FB1 IP。
Primary、RTSI、EliteDriver 示例是否连接 Primary/RTSI/FB2 IP。
本机 IP 是否和机器人在同一网段。
虚拟机是否使用桥接网络。
VPN、防火墙是否影响机器人回连本机端口。
external_control.script 是否存在于 Python 包目录。
运动示例运行前，机器人周围环境是否安全。

目录

首页 二次开发 Python CS 机器人 Python SDK 快速使用手册