Skip to main content

Step-by-step tutorial

Video tutorial​

We have prepared a video tutorial for you, so you can learn all about it here.

Click here to watch the video tutorial

Basic tutorial​

In this tutorial, we will develop a program with the following functionalities:

  1. Start the control system;
  2. Set the operation mode;
  3. Set the teach speed;
  4. Set the teach coordinate system;
  5. Enable the servo;
  6. Teach the robot to move forward on joint axis 1;
  7. Disable the servo;
  8. Get the current position of the robot.

Project initialization​

Import the basic libraries and nrcAPI.h header file, and create a new main function:

#include <iostream>
#include "unistd.h"
#include "nrcAPI.h"
#include <string.h>
#include <queue>
#include <list>
#include <sstream>
#include<stdio.h>
using namespace std;

int main()
{

}

In this way, our project is initialized.

Note: In order to save space, the following code no longer contains irrelevant code such as #include

System startup​

Boot-up is the beginning of everything. So, we need to start the control system in the program.

Define a function SystemStartup()

void  SystemStartup(){
cout<<"Library version:"<< NRC_GetNexMotionLibVersion()<<endl;//Output NexMotion library version information
NRC_StartController();  //Start control system
while(NRC_GetControlInitComplete() != 1)  //Detect whether the control system is initialized
{
NRC_Delayms(100);   //Delay 100ms
cout << "Starting Controller" << endl;
}
}

In the code, we mainly use the following interfaces:

  • NRC_GetNexMotionLibVersion(): Get NexMotion library version information
  • NRC_StartController(): Start the control system
  • NRC_GetControlInitComplete(): Get the initialization status of the controller, true means success, false means not yet initialized successfully
  • NRC_Delayms(): Delay function, in milliseconds (ms)

In the code below, we call the SystemStartup() function in the main function

int main()
{
SystemStartup()
}

Switch operation mode​

The control system has three operation modes: teach, run, and remote. In this tutorial, because we want to achieve jog (teach) motion of the robot, we need to switch the operation mode to teach mode in the program.

Add NRC_SetOperationMode(NRC_TEACH_); to the main function to switch the operation mode to teach mode.

int main (){
SystemStartup();
NRC_SetOperationMode(NRC_TEACH_);
}

NRC_TEACH_ is used in the code, and the definition can be found in the nrcAPI.h file, which means teach mode.

Set servo status​

Before enabling the robot, we need to switch the servo to the ready status.

NRC_SetServoReadyStatus(1)

Set teach motion coordinate system​

The coordinate system is divided into joint coordinate system, Cartesian coordinate system, tool coordinate system and user coordinate system. Since we want to make the robot joint axis 1 move, we need to switch to the joint coordinate system first. To switch the coordinate system, use the following interface.

NRC_SetCurrentCoord(NRC_ACS)

NRC_ACS is used in the code, and the definition can be found in the nrcAPI.h file, which means the joint coordinate system.

Set teach speed​

It is necessary to set the movement speed of the robot in the teach mode.

The speed in teach mode is a percentage. For example, if we want to set the teach speed to 20%, then the following interface can be used.

NRC_SetTeachRunSpeedPer(20)

Preliminary preparation completed​

At this point, our code should now look like this:

void  SystemStartup(){
cout<<"Library version:"<< NRC_GetNexMotionLibVersion()<<endl;//Output NexMotion library version information
NRC_StartController();  //Start control system
while(NRC_GetControlInitComplete() != 1)  //Detect whether the control system is initialized
{
NRC_Delayms(100);   //Delay 100ms
cout << "Starting Controller" << endl;
}
}
int main (){
SystemStartup();  //Start control system
NRC_SetOperationMode(NRC_TEACH_);  //Switch to teach mode
NRC_SetServoReadyStatus(1);  //Switch servo to ready status
NRC_SetCurrentCoord(NRC_ACS);  //Switch coordinate system to joint coordinate system
NRC_SetTeachRunSpeedPer(20);  //Set running speed to 20%
}

Now, we are ready to run.

Servo power on​

After the servo is set to Ready state, power on the servo by calling NRC_ServoEnable();.

Move axis 1​

Use NRC_JogMove(1,1) to jog the robot. The first parameter is the axis, which determines whether it is a joint motion or a synthetic motion depending on the coordinate system. For example, in the joint coordinate system, 1 means the joint axis 1, and in the Cartesian coordinate system, 1 means the axis X. The second parameter indicates forward and reverse direction, 1 for forward motion, -1 for reverse motion.

But just one instruction is not enough!

To prevent a robot collision due to communication interruptions after issuing this instruction, it is required to send the instruction every 200ms for continuous operation.

For example, if we want to make axis 1 move continuously in the positive direction for 2 seconds, then we need to add the following code:

for(int i = 0 ; i < 10 ; i++)
{
NRC_JogMove(1,1);
NRC_Delayms(200);   //Delay 200ms
}
NRC_JogMoveStop(1);//Stop jogging axis 1

Servo power off​

After the motion is completed, execute NRC_ServoDisable().

View current position​

To determine the current position of the robot, we need to define an object to receive the position values.

NRC_Position position

The definition of NRC_Position position structure can be found in nrcAPI.h.

Then add the following in the code

NRC_GetCurrentPos(NRC_ACS, position);
printf("position.pos=%f,%f,%f,,%f,%f,%f,\n",position.pos[0],position.pos[1],position.pos[2],position.pos[3],position.pos[4],position.pos[5]);

The purpose is to get the data of the joint coordinate system, store the data in the inexbot object, and then print it out.

Completion​

At this point, our code should look like this:

void  SystemStartup(){
cout<<"Library version:"<< NRC_GetNexMotionLibVersion()<<endl;//Output NexMotion library version information
NRC_StartController();  //Start control system
while(NRC_GetControlInitComplete() != 1)  //Detect whether the control system is initialized
{
NRC_Delayms(100);   //Delay 100ms
cout << "Starting Controller" << endl;
}
}
int main (){
SystemStartup();  //Start control system
NRC_SetOperationMode(NRC_TEACH_);  //Switch to teach mode
NRC_SetServoReadyStatus(1);  //Switch servo to ready status
NRC_SetCurrentCoord(NRC_ACS);  //Switch coordinate system to joint coordinate system
NRC_SetTeachRunSpeedPer(20);  //Set running speed to 20%
NRC_ServoEnable(); //Servo power on
for(int i = 0 ; i < 10 ; i++)
{
NRC_JogMove(1,1);
NRC_Delayms(200);   //Delay 200ms
NRC_JogMoveStop(1);//Stop jogging axis 1
}
NRC_ServoDisable();  //Servo power off
NRC_Position position;  //Define position object
NRC_GetCurrentPos(NRC_ACS, position);  //Get the current position in the joint coordinate system to the position object
printf("position.pos=%f,%f,%f,,%f,%f,%f,\n",position.pos[0],position.pos[1],position.pos[2],position.pos[3],position.pos[4],position.pos[5]);  //Print position
}

Now, a DEMO program that integrates the following functions is finished: start control system; set operation mode; set teach speed; set teach coordinate system; servo power on; jog the robot joint axis 1 forward motion; servo power off; and get robot current position

You can now refer here to compile our code into an executable file and transfer it to the controller to run!

Project advancement​

Errors and messages​

Problems will inevitably occur during operation, and the control system will send out an error message at this time. We need to receive these messages in the program.

Callback function​

First we need to define a callback function to be called after receiving the message

void msgHook()
{
NRC_Messsage tmp;  //Define a message structure object
NRC_GetMesssage(1, tmp);  //Assign the earliest message in the message queue to the object tmp
printf("msgHook  localTime=%d:%d::%d, 0x%x,0x%x,text=%s,size=%d\n",tmp.localTime.minute, tmp.localTime.second, tmp.localTime.milliseconds, tmp.kind, tmp.type, tmp.text.c_str(),NRC_GetMesssageSize());
}

The NRC_Message structure is used, and related definitions can be found in the nrcAPI.h file.

Setting​

Then call the following in the SystemStartup() function of the startup system

NRC_SetMsgHappenCallback(msgHook)

NRC_SetMsgHappenCallback() is used to set the callback function to be called when the message occurs.

Clear error​

After an error occurs, you need to clear the error before you can continue running.

Call NRC_ClearAllError() to clear all errors, including the message queue. But not all problems can be cleared. There are some servo-related errors that need to be checked for wiring and other problems before they can be cleared.

Set robot type​

Setting the robot type is the prerequisite for the robot to operate properly. This interface supports four types of robot. Set the robot type by calling the function NRC_SetRobotTypeConfig(std::string type).

The parameter type indicates the robot type:

  • "R_GENERAL_6S" means 6-axis

  • "R_SCARA" means 4-axis SCARA

  • "R_FOURAXIS_PALLET" means 4-axis palletizing

  • "R_FOURAXIS" means 4-axis

For example, to set the robot type to a 6-axis robot, insert the following code:

int main(){
NRC_SetRobotTypeConfig("R_GENERAL_6S");
}

After setting the robot parameters, the teach pendant needs to be restarted for the changes to take effect.

Servo mapping​

Call the NRC_SetAllServoMapRelation function to set the servo mapping.

std::vector<int> servoMap = { 0,0, 0,0, 0,0 };//Robot mapping
int syncGroupNum = 0;//External axis group number
int syncType[]={0,0,0};//External axis type
std::vector<std::vector<int>> syncServoMap={{0,0},{0,0},{0,0}};//External axis mapping
NRC_SetAllServoMapRelation(servoMap,syncGroupNum, syncType, syncServoMap);

Set robot parameters​

Robot DH parameter configuration​

//Structure
struct NRC_RobotDHConfig
{
    double L1; ///<L1 rod length
    double L2; ///<L2 rod length
    double L3; ///<L3 rod length
    double L4; ///<L4 rod length
    double L5; ///<L5 rod length
    double L6; ///<L6 rod length
    double L7; ///<L7 rod length
    double theta; ///<Axis 5 direction, only valid for 6-axis robots, optional parameters: 0, 90
    double CoupleCoe12; ///<1/2 axis coupling ratio
    double CoupleCoe23; ///<2/3 axis coupling ratio
    double CoupleCoe32; ///<3/2 axis coupling ratio
    double CoupleCoe34; ///<3/4 axis coupling ratio
    double CoupleCoe45; ///<4/5 axis coupling ratio
    double CoupleCoe46; ///<4/6 axis coupling ratio
    double CoupleCoe56; ///<5/6 axis coupling ratio
};

Use the struct class NRC_RobotDHConfig to define an object named 'config'. You can then set the robot's DH parameters using the interface function NRC_SetRobotDHConfig(NRC_RobotDHConfig config). Please note that when setting the DH parameters, ensure that the servo is in a stopped or ready state.

Example:

NRC_RobotDHConfig robotDHConfig = {321.5, 270,70,299, 78.5, 50, 0, 90, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0};//DH parameter configuration
NRC_SetRobotDHConfig(robotDHConfig );//Set DH parameter configuration

Fill in the DH parameters according to the actual parameters of the robot.

Robot joint parameter configuration​

//Structure
struct NRC_RobotJointConfig
{
  double reducRatio; ///<Reduction ratio
  int encoderResolution; ///<Encoder bits
  double posSWLimit; ///<Axis positive limit, unit: degree
  double negSWLimit; ///<Axis reverse limit, unit: degree
  double ratedRotSpeed; ///<Motor rated positive rpm, unit: rpm
  double ratedDeRotSpeed; ///<Motor rated reverse rpm, unit: rpm
  double maxRotSpeed; ///<Motor maximum positive rpm, a multiple of the motor rated positive rpm, unit: times
  double maxDeRotSpeed; ///<Motor maximum reverse rpm, a multiple of the motor rated reverse rpm, unit: times
  double maxAcc; ///<Maximum acceleration, a multiple of the rated positive speed, unit: times, rated positive speed = motor rated positive rpm / reduction ratio * 6
  double maxDecel; ///<Maximum deceleration, a multiple of the rated reverse speed, unit: times, rated reverse speed = motor rated reverse rpm / reduction ratio * 6
  int direction; ///<Model direction, 1: positive, -1: reverse. If you want to change the direction of the robot's single joint movement, usually modify the model direction
  int AxisDirection;///<Joint actual direction
};

In the configuration structure of the robot joint parameters, the axis positive limit refers to the maximum range in the positive direction of the robot joint, and the axis reverse limit refers to the maximum range in the reverse direction of the robot joint (this value must be a negative number).

Like the robot DH parameter configuration, use the structure class NRC_RobotJointConfig to define an object config and write in the appropriate parameters.

Setting the robot joint parameters is realized by calling the function NRC_SetRobotJointConfig(int axisNum, NRC_RobotJointConfig config), the parameter axisNum is the number of the axis to be set, and the parameter range is: 1 <= axisNum <= the total number of robot axes. For the parameter configuration, please refer to the function NRC_RobotJointConfig. Please note that when setting the robot joint parameters, ensure that the servo is in a stopped or ready state.

Example:

NRC_RobotJointConfig robotJointConfig = {121,17,  55, -55, 4000, -4000, 1,-1,2.12, -2.12, 1,1};//Joint parameter configuration
for (int i=1; i<7; i++)
{
    NRC_SetRobotJointConfig(i,robotJointConfig);
}//Setting

When filling in the joint parameters, set the joint limit of each axis according to the actual working environment. Set the limit of each joint to -9999 ~ 9999, and then jog each axis of the robot individually to check whether the positive direction of each axis of the robot is correct.