Skip to main content

User Guide

This chapter introduces how to configure and run an xCore SDK C++ program.

For other language versions (Python, Java, C#), please refer to separate manuals.

1 Setup​

1.1 Hardware Setup​

For hardware setup of the robot body and control cabinet, please refer to the "xCore Control System User Manual V3.0.1". Except for network configuration, no other additional hardware setup is required to use the xCore SDK.

1.2 Network Configuration​

The xCore SDK connects to the robot via Ethernet (TCP/IP). Both wired and wireless connections are supported, allowing the user PC and robot to be connected to the same local area network. If only non-real-time control is used, network performance requirements are not high, and wireless connection can be used.

For real-time control, it is recommended to connect directly to the robot via wired connection. The robot is equipped with 2 network ports, one for external network and one for direct connection. The default static IP address for the direct connection port is 192.168.0.160. There are two ways to connect to the robot:

  • Connection Method 1: Direct connection between robot and user PC using network cable. If the user industrial PC and robot are not on the same subnet, the user PC's IP needs to be configured to be on the same subnet as the robot's static IP address, for example 192.168.0.22.

  • Connection Method 2: The robot's external network port connects to a router or switch, and the user PC also connects to the router or switch, with both on the same local area network.

Note: Method 1 is recommended for connection. Poor network communication quality with Method 2 may cause unstable robot motion.

1.3 Robot Function Settings​

No settings need to be made through RobotAssist; users can directly control the robot using the xCore SDK.

After switching to real-time mode, the robot will remain on after restart and automatically switch to automatic mode.

2 Compilation​

2.1 xCore SDK Package Description​

xCoreSDK
├── doc: Documentation and user manuals
├── example: Sample programs
├── external: Eigen
├── include: Header files
└── lib: Library files for various operating systems and architectures

2.2 C++ Compilation​

The xCoreSDK version uses CMake to build projects, with CMake version not lower than 3.12.

2.2.1 Linux Platform Compilation​

cd xCoreSDK-v0.5.0
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=../out
cmake --build . --target sdk_example
cmake --build . --target install

2.2.2 Windows Platform Compilation​

  1. Download and install Microsoft Visual Studio 2017 or later, selecting "Desktop development with C++".

  2. Open the CMake project, selecting the CMakeLists.txt in the root directory.

  3. Select to compile Release or Debug, and compile the sample programs.

2.2.3 QT Platform Compilation​

  1. Download and install Qt5.15.2 or later, and select MSVC2019 compiler;
  2. Save the SDK package locally (no Chinese path);
  3. Create a new project file, and select MSVC2019 as the compiler;
  4. Enter the configuration file (.pro file), and input the following configuration statements:
DEFINES += _USE_MATH_DEFINES
LIBS += -L <path-to-library-directory> -lxCoreSDK
INCLUDEPATH += <path-to-include-directory>
#Eigen configuration
INCLUDEPATH += <path-to-external-directory

Static library compilation example:

DEFINES += _USE_MATH_DEFINES

#SDK
LIBS += -L$$PWD/xCoreSDK-v0.5.0/lib/Windows/Debug/64bit -lxCoreSDK
INCLUDEPATH += xCoreSDK-v0.5.0/include

#Eigen
INCLUDEPATH += xCoreSDK-v0.5.0/external

3 Local Configuration Files​

3.1 Runtime Logs​

After running the SDK program and connecting to the robot, the SDK will print logs to files when calling interfaces for setting data, executing operations, etc., including calling parameters and return results. These logs can be provided to Rokae technical support personnel for analysis and troubleshooting when issues occur.

Default log settings:

  • File path: <Current working directory>/_rokae_log_/<robot uid>/xCoreSDK_<YYYY-MM-DD>.log

  • Maximum retention of 7 days of logs

User-defined configuration of log output location and retention days is currently supported. Users need to place a file named user_log_settings.json in the program running directory, with the following file structure:

{
	"_log_storage_directory_": "user_defined_log_storage_directory",			
	"_retention_days_":5
	}

_log_storage_directory_ is the user-specified log storage directory path, replacing the default log storage directory _rokae_log_. It is recommended to use relative paths; _retention_days_ is the log retention days.

Global logs are also currently provided, with the global log output location fixed in a folder named logs in the program running directory, with a maximum retention of 7 days of global logs.

3.2 Real-Time Mode Waiting Timeout Setting​

The default waiting timeout for receiving status data in real-time mode is 1ms. According to the actual network conditions on site, you can add a configuration file xcoresdk_config.json in the same directory as the executable file to set the timeout to adapt to actual conditions and optimize real-time effects. If the device network conditions are good and there is a delay in executing motion commands after controlling for a period of time, you can appropriately increase the timeout. The setting range is 1~4ms. The specific json file format is as follows:

{
	"rt":{
		"_timeout_": 1
	}
}

4 Language​

The xCore SDK error code information and exception information support Chinese and English, depending on the system language set on the user's PC. If set to display Chinese, Chinese error information is returned; otherwise, English error information is returned.

5 Linux Real-Time Environment Configuration (Optional)​

The xCore controller real-time mode receives motion commands with a period of 1ms, and the client needs to ensure at least a 1kHz sending period. If the computation is large, it is recommended to install a real-time kernel.

5.1 Install Dependencies​

apt-get install build-essential bc curl ca-certificates fakeroot gnupg2 libssl-dev lsb-release libelf-dev bison flex cmake libeigen3-dev

5.2 Download Real-Time Kernel Patch​

The uname -r command can tell you the kernel currently in use on this machine;

Find the kernel closest to the current kernel version through the website https://www.kernel.org/pub/linux/kernel/projects/rt/;

Download files:

$ curl -SLO https://www.kernel.org/pub/linux/kernel/v4.x/linux-4.14.12.tar.xz
$ curl -SLO https://www.kernel.org/pub/linux/kernel/v4.x/linux-4.14.12.tar.sign
$ curl -SLO https://www.kernel.org/pub/linux/kernel/projects/rt/4.14/older/patch-4.14.12-rt10.patch.xz
$ curl –SLO https://www.kernel.org/pub/linux/kernel/projects/rt/4.14/older/patch-4.14.12-rt10.patch.sign

If the domestic network speed is very slow, you can download directly from the website or find other mirror sources;

Decompress:

$ xz -d linux-4.14.12.tar.xz
$ xz -d patch-4.14.12-rt10.patch.xz

Check sign file integrity

$ gpg2 --verify linux-4.14.12.tar.sign

You will get information similar to the following:

$ gpg2--verify linux-4.14.12.tar.sign 
gpg: assuming signed data in 'linux-4.14.12.tar'
gpg: Signature made Fr 05 Jan 2018 06:49:11 PST using RSA key ID 6092693E
gpg: Can't check signature: No public key

Note down ID 6092693E and execute:

$ gpg2--keyserver hkp://keys.gnupg.net--recv-keys 0x6092693E

Similarly for the patch file, perform the same operation.

After downloading the server key, verify again. If you get the following information, it is correct.

$ gpg2--verify linux-4.14.12.tar.sign
gpg: assuming signed data in 'linux-4.14.12.tar'
gpg: Signature made Fr 05 Jan 2018 06:49:11 PST using RSA key ID 6092693E
gpg: Good signature from "Greg Kroah-Hartman &lt;gregkh@linuxfoundation.org&gt;"[unknown]
gpg: aka "Greg Kroah-Hartman &lt;gregkh@kernel.org&gt;"[unknown]
gpg: aka "Greg Kroah-Hartman (Linux kernel stable release signing key)<greg@kroah.com>"[unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner. Primary key
fingerprint: 647F 2865 4894 E3BD 4571 99BE 38DB BDC8 6092 693E

Similarly verify the patch file.

5.3 Compile Kernel​

Decompress:

$ tar xf linux-4.14.12.tar
$ cd linux-4.14.12
$ patch -p1 < ../patch-4.14.12-rt10.patch

Configure kernel:

$ make oldconfig

The following information appears:

Preemption Model
	1. No Forced Preemption (Server) (PREEMPT_NONE)
	2. Voluntary Kernel Preemption (Desktop) (PREEMPT_VOLUNTARY)
	3. Preemptible Kernel (Low-Latency Desktop) (PREEMPT_LL) (NEW)
	4. Preemptible Kernel (Basic RT) (PREEMPT_RTB)(NEW)
 >5. Fully Preemptible Kernel (RT) (PREEMPT_RT_FULL)(NEW)

Select 5 and keep pressing enter.

Start compiling:

$ fakeroot make-j4 deb-pkg

dpkg installation:

$ sudo dpkg -i ../linux-headers-4.14.12-rt10_*.deb ../linux-image-4.14.12-rt10_*.deb

5.4 Verify Installation Success​

Restart, enter Ubuntu advanced options, and you can see the kernel you installed. After selecting the newly installed kernel to enter, check the corresponding kernel version through uname -r. If the version is correct, the content in /sys/kernel/realtime is 1.

Last updated on