SDK简介

概述

xCore SDK 编程接口库是珞石机器人提供给客户用于二次开发的软件产品，通过编程接口库，客户可以对配套了 xCore 系统的机器人进行一系列控制和操作，包括实时和非实时的运动控制，机器人通信相关的读写操作，查询及运行RL工程，等等。该使用说明书主要介绍编程接口库的使用方法，以及各接口函数的功能。用户可编写自己的应用程序，集成到外部软硬件模块中。

兼容性

控制器版本和机器人型号

• 控制器版本：xCore v3.0.1 及以后。

• 机器人型号：支持控制所有机型，根据协作和工业机器人支持的功能不同，可调用的接口有所差别。

编译平台及语言

操作系统	编译器	平台	语言
Ubuntu 18.04/20.04/22.04	build-essential	x86_64 aarch64	C++,Python
Windows 10	MSVC 14.1+	x86_64	C++,Python,C#
Android		armeabi-v7a,arm64-v8a,x86,x86_64	Java

非实时控制

xCore SDK提供对机器人的非实时控制，主要通过给机器人发送运动指令，使用控制器内部的轨迹规划，完成路径规划和运动执行。非实时模式提供的操作有：

• 运动：轴空间运动（MoveAbsJ,MoveJ），笛卡尔空间运动（MoveL,MoveC,MoveCF,MoveSP），支持导轨联动。及可达性校验，设置加速度等
• 力控指令
• 机器人通信：数字量和模拟量 I/O，寄存器读写，XMS 和 XMC 机型末端 485 通信
• RL工程的查询与执行
• 拖动与路径回放（只针对 xMate 协作机器人）
• 其他操作：Jog，设置碰撞检测，软限位，清除报警，查询控制器日志等等

实时控制

1. 概况

xCore SDK 的实时控制包含了一系列底层控制接口，科研或二次开发用户可以使用该软件包实现最高达 1KHz 的实时控制，用于算法验证以及新应用的开发。

• xMate协作机器人支持5种控制模式：
  • 轴空间位置控制
  • 笛卡尔空间位置控制
  • 轴空间阻抗控制
  • 笛卡尔空间阻抗控制
  • 直接力矩控制
• 6轴工业机器人支持2种位置控制模式：
  • 轴空间位置控制
  • 笛卡尔空间位置控制
• 工业3、4轴机型暂不支持。

2. 最低系统和网络要求

此页面仅指定了运行 Roake控制接口（RCI）的要求。其他要求在收到的机器人文档中指定

2.1 工作站PC

最低系统要求
操作系统	Linux实时内核，
网卡	Realtek型号的网卡，不建议使用Inter型号的网卡

由于机器人以 1kHz 的频率发送数据，因此将工作站 PC 配置为尽可能低延迟是很重要的。例如，建议 禁用CPU频率缩放。其他可能的优化将取决于特定系统。

2.2 禁用 CPU 频率缩放

CPU 通常配置为在轻负载下使用较低的工作频率，以节省电力。我们建议禁用此功能，因为它会在使用 Rokae 时导致高延迟. 要检查和修改省电模式，请安装 cpufrequtils 软件包：

sudo apt install cpufrequtils

运行 cpufreq-info 来查看可用的调控器 “governors” 和当前的CPU频率。下面是一个示例输出：

$ cpufreq-info
...
analyzing CPU 0:
  driver: intel_pstate
  CPUs which run at the same hardware frequency: 0
  CPUs which need to have their frequency coordinated by software: 0
  maximum transition latency: 0.97 ms.
  hardware limits: 400 MHz - 3.00 GHz
  available cpufreq governors: performance, powersave
  current policy: frequency should be within 400 MHz and 3.00 GHz.
                  The governor "powersave" may decide which speed to use
                  within this range.
  current CPU frequency is 500 MHz.

在此示例中，最大频率为 3 GHz，但由于节电策略，当前频率为 500 Mhz。在这种情况下，我们可以通过将调控器设置为性能模式来受益。

要使用 Ubuntu GUI 更改此设置，请安装该 indicator-cpufreq 软件包。Unity 用户界面顶部栏中（即屏幕顶部）的小部件应允许设置当前策略。

要使用终端更改此设置，请执行以下命令：

sudo systemctl disable ondemand
sudo systemctl enable cpufrequtils
sudo sh -c 'echo "GOVERNOR=performance" > /etc/default/cpufrequtils'
sudo systemctl daemon-reload && sudo systemctl restart cpufrequtils

这将禁用 ondemand CPU 缩放守护进程，创建一个 /etc/default/cpufrequtils 配置文件，然后重新启动 cpufrequtils 服务。

启用 performance 调控器后，cpufreq-info 结果为：

$ cpufreq-info
...
analyzing CPU 0:
  driver: intel_pstate
  CPUs which run at the same hardware frequency: 0
  CPUs which need to have their frequency coordinated by software: 0
  maximum transition latency: 0.97 ms.
  hardware limits: 400 MHz - 3.00 GHz
  available cpufreq governors: performance, powersave
  current policy: frequency should be within 400 MHz and 3.00 GHz.
                  The governor "performance" may decide which speed to use
                  within this range.
  current CPU frequency is 2.83 GHz.

现在示例输出显示 CPU 频率接近最大频率。也可以使用 cpufreq-info -p 命令直接验证当前的调控器。

2.3 网络

如果可能，请将工作站 PC 直接连接到控制器 Control 的 LAN 端口，即避免任何中间设备，如交换机。中间有中继可能会导致延迟、抖动或数据包丢失。这会降低控制器的性能或使其无法使用

为了控制机器人，必须保证以下时间测量之和小于 1ms:

• 工作站 PC 与 RCI 之间的往返时间（Round trip time [RTT]）
• 运动生成器（motion generator）或控制环路（control loop）的执行时间
• 机器人处理数据和步进内部控制器所需的时间

3. 实时控制循环的最佳实践

在使用Rokae 实现 1 kHz 控制循环时，务必确保代码能在 1ms 的时限内执行完毕。也就是说，从读取到写入指令之间的全部操作，必须在 1ms 内完成。

在以下情况下，时限可能会不可控：

• 使用交换机连接控制电脑
• 网卡性能不足
• 未使用实时内核

3.1 1 kHz 控制循环中不应该做的事

❌ 不要：在循环中加载文件或者模型

  std::function<CartesianPosition()> callback = [&, rtCon]()
  {
      time += 0.001;
      double delta_angle = M_PI / 20.0 * (1 - std::cos(M_PI / 2.5 * time));
      JointPosition cmd = {{jntPos[0] + delta_angle, jntPos[1] + delta_angle, jntPos[2] - delta_angle,
                            jntPos[3] + delta_angle, jntPos[4] - delta_angle, jntPos[5] + delta_angle,
                            jntPos[6] - delta_angle}};
      if (time > 60)
      {
          cmd.setFinished(); // 60秒后结束
      }
      //不要使用
      traceOfsLoop_.open(("get" +
                          std::to_string(std::chrono::duration_cast<std::chrono::milliseconds>(
                                             std::chrono::system_clock::now().time_since_epoch())
                                             .count()) +
                          ".txt"),
                         std::ios::out);
      return cmd
  };

❌ 不要：使用 sleep 或阻塞操作

 std::function<CartesianPosition()> callback = [&, rtCon]()
 {
     time += 0.001;
     double delta_angle = M_PI / 20.0 * (1 - std::cos(M_PI / 2.5 * time));
     JointPosition cmd = {{jntPos[0] + delta_angle, jntPos[1] + delta_angle, jntPos[2] - delta_angle,
                           jntPos[3] + delta_angle, jntPos[4] - delta_angle, jntPos[5] + delta_angle,
                           jntPos[6] - delta_angle}};
     if (time > 60)
     {
         cmd.setFinished(); // 60秒后结束
     }
     //不要使用
     std::this_thread::sleep_for(std::chrono::milliseconds(1));
     return cmd;
         
 };

❌ 不要：在每个循环中打印输出

 std::function<CartesianPosition()> callback = [&, rtCon]()
 {
     time += 0.001;
     double delta_angle = M_PI / 20.0 * (1 - std::cos(M_PI / 2.5 * time));
     JointPosition cmd = {{jntPos[0] + delta_angle, jntPos[1] + delta_angle, jntPos[2] - delta_angle,
                           jntPos[3] + delta_angle, jntPos[4] - delta_angle, jntPos[5] + delta_angle,
                           jntPos[6] - delta_angle}};
     if (time > 60)
     {
         cmd.setFinished(); // 60秒后结束
     }
     //不要使用
     print(std::cout, "jntPos:", jntPos);
     return cmd
 };

❌ 不要：在循环中进行动态内存分配

 std::function<CartesianPosition()> callback = [&, rtCon]()
 {
     time += 0.001;
     double delta_angle = M_PI / 20.0 * (1 - std::cos(M_PI / 2.5 * time));
     JointPosition cmd = {{jntPos[0] + delta_angle, jntPos[1] + delta_angle, jntPos[2] - delta_angle,
                           jntPos[3] + delta_angle, jntPos[4] - delta_angle, jntPos[5] + delta_angle,
                           jntPos[6] - delta_angle}};
     if (time > 60)
     {
         cmd.setFinished(); // 60秒后结束
     }
     //不要使用
	  char* p = new char[64];
	  return cmd；
 };

为什么内存分配会产生影响：

• Heap allocations 堆内存分配 （例如 std::vector, Eigen::VectorXd）的速度非常慢
• 在 1 kHz 频率下，即便是很小的分配也会积累起来，导致系统抖动
• 预先分配内存可以保证系统行为的确定性和实时性

API支持

下表是各语言版本接口支持情况概览。

模块	API 功能	C++	Python & C#	Android
rokae::Robot	基本操作	全部支持	全部支持	全部支持
rokae::Robot	非实时运动	全部支持	全部支持	全部支持
rokae::Robot	Jog 机器人	全部支持	全部支持	全部支持
rokae::Robot	通信	全部支持	全部支持	全部支持
rokae::Robot	RL 工程	全部支持	全部支持	全部支持
rokae::Robot	协作相关	全部支持	部分支持	全部支持
rokae::Model	运动学计算	全部支持	全部支持	全部支持
rokae::ForceControl	力控指令	全部支持	全部支持	全部支持
rokae::RtMotionControl	实时模式	全部支持	不支持	不支持
rokae::Planner	上位机路径规划	全部支持	不支持	不支持
rokae::xMateModel	运动学和动力学计算	全部支持	不支持	不支持