快速开始
环境配置
如需安装 Ubuntu 和 Python 环境请参考官方文档
-
Ubuntu 22.04 LTS 的安装方法请参考 Ubuntu 官方安装说明 官方安装文件下载
-
Python 官方网站
确认关闭电源的节能模式，并开启均衡/性能模式
如果你的电脑是节能模式，在进行数据采集录制时可能会导致采集的数据帧率不够，请确认开启均衡模式/性能模式
或者用命令行进行操作开启性能模式
echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor局域网络配置指导
网线连接机器人
用网线连接个人 PC 和机器人
配置个人 PC 的局域网 IP
- 打开个人 PC 的设置-网络-有线的配置
- 设置 IP 为手动配置，并填写 IP 地址和子网掩码
配置完成后点击应用
临时配置机器人的局域网 IP
该方式配置的局域网 IP 在机器人重启后失效，需要重新配置。
!ssh 登录需要预先配置好机器人的 WIFI 和无线 IP，参考以下步骤SSH 登录机器人前，需要先为机器人本体配置 WiFi，并记录机器人当前无线 IP。
WiFi网络配置
-
通过已有的远程连接方式进入机器人本体桌面。机器人需要已经具备可用的 5G 或 WiFi 远程连接，才能进行远程桌面操作。
-
在机器人本体桌面内打开浏览器，输入：
http://localhost/正常情况下会进入“网络设置”页面。如果没有自动进入，可直接输入：
http://localhost/robot/network-
点击“扫描WiFi列表”，选择需要连接的 WiFi 网络，输入密码并点击“连接”。
-
连接成功后，记录页面显示的机器人无线 IP。
注意： 不要在主臂支架 PC 或个人 PC 的浏览器中输入 http://localhost/，此时 localhost 指向当前 PC。主臂支架上的 http://localhost/ 是主臂支架 WebUI，不是机器人网络设置页。不要使用 http://ex001-xxx 作为通用入口，除非已经确认当前 PC 能够正确解析该机器人主机名。
点击扫描WiFi列表，会显示出当前可以连接的WiFi网络
选择适合的WiFi网络，输入正确密码，即可连接成功。
WiFi 配置完成后，在个人 PC 上使用机器人实际无线 IP 登录：
- ssh 登录到机器人（xr 用户密码：123）
ssh xr@机器人无线网IP登录成功后，再继续执行本节后续的网口发现和临时局域网 IP 配置步骤。
- 找到和个人 PC 连接的网口
ifconfig通过看连接网线前后的接口状态变化（从没有 RUNNING 到 RUNNING）看是哪一个网口
- 添加对应网口的局域网 IP 和掩码
sudo ip addr add 192.168.10.1/24 dev enp2s0永久配置机器人 IP
远程桌面连接后可视化配置
PC 上用 RustDesk 远程访问机器人 IP 地址，正常情况下机器人出厂都会有 RustDesk
连接后需要输入密码，密码为：X2robot.com 即可进入机器人桌面，xr 用户密码：123
设置 IP 为手动配置，并填写 IP 地址和子网掩码
配置完成后点击 Apply 应用
用 nmcli 命令配置 IP
也可以 ssh 登陆上机器人之后用 nmcli 配置， 记得把接口名 enp2s0 替换成实际需要修改的接口名
# 配置ip
sudo nmcli device modify "enp2s0" \
ipv4.method manual \
ipv4.addresses 192.168.10.1/24 \
ipv4.gateway "" \
ipv4.dns "" \
connection.autoconnect yes重启网口
配置好机器人和本地 PC 的 IP 之后，需要重启一下网口才能生效，重启任一端即可
通过命令行重启
*# 查看网口*
ifconfig
*# 重启网口*
sudo ifconfig eth0 down
sudo ifconfig eth0 up或者通过 UI 点击关闭之后再重新开启
确认连通性
最后在个人 PC 上 ping 一下确认是否连通
ping 192.168.10.1
SDK 安装
安装依赖
sudo apt-get update
sudo apt install python3-pip
sudo apt install ffmpeg更新 pip 镜像源（For 国内用户）
安装 SDK 时部分依赖下载可能会很慢，国内用户可以更换 pip 镜像源进行下载
# 配置为清华大学源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
# 或配置为阿里云源
# pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/虚拟环境配置
Ubuntu 24.04 和 Ubuntu 22.04 的默认 Python 版本可能有区别，用户需要根据自身的安装版本配置虚拟环境
# Ubuntu **24.04 **安装Python依赖虚拟环境
sudo apt install python3.12-venv
# Ubuntu **22.04** 安装Python依赖虚拟环境
# sudo apt install python3.10-venv
# 创建虚拟环境
python3 -m venv .venv
# 激活虚拟环境
source .venv/bin/activate安装 sdk
#根据https://github.com/X-Square-Robot/sdk_robot/releases的版本 安装whl包
pip install x2robot-1.0.0-py3-none-any.whl运行第一个程序
连接测试
创建 check_connect.py：
from typing import Annotated
import typer
from x2robot import connect
from x2robot.sdk import PingRequest
def main(
server: Annotated[
str,
typer.Option(help="server address, e.g., localhost:50051"),
] = "localhost:50051",
):
robot = connect(f"x2://{server}")
request = PingRequest(payload="Hello, X2Robot!")
response = robot.benchmark.ping(request)
if response.payload == "Pong to: Hello, X2Robot!":
print("Connection to X2Robot SDK server successful!")
print(f"Response payload:[{response.payload}]")
else:
print("Unexpected response:", response.payload)
if __name__ == "__main__":
typer.run(main)运行程序
# 将地址替换为实际的机器人 IP 和 SDK Server 端口
python3 check_connect.py --server 192.168.10.1:50051
# 预期输出示例
Connection to X2Robot SDK server successful!
Response payload:[Pong to: Hello, X2Robot!]--server 参数格式为 机器人 IP:端口，不需要添加 x2://。示例程序会在调用 connect() 时自动构造完整连接地址。
其他功能示例
参考 https://github.com/X-Square-Robot/sdk_robot/tree/main/examples 里面的示例或者下面压缩包里的示例，以调用基础示例章节里定义的接口
运行 examples 的示例需要加上参数 \-\-server 机器人 IP:50051
Eg: python3 head_control.py --server 192.168.10.1:50051
卸载 SDK
更新版本时需要将之前版本 SDK 卸载
! 卸载也需要在 SDK 虚拟环境中执行
# 卸载x2robot，假设你之前装了0.1.8版本
pip uninstall x2robot-0.1.8-py3-none-any.whl