主站库
介绍
纳博特Ethercat主站控制器主站抖动时间小于20us。可广泛应用于工业自动化控制系统的开发，特别适用于机器人、伺服电机控制等实时性要求高的场景。
版本信息
| 二次开发版本 | 公司 |
|---|---|
| 1.0.0 | INEXBOT |
版本迭代
| 版本 | 修改日期 | 修改人 | 描述 |
|---|---|---|---|
| 1.0.0 | 20250310 | EA | 初始版本 |
概述
关于文档
本文旨在帮助用户使用纳博特Ethercat的主站控制的C++库libNexIghEcm。
关于libNexIghEcm库
该库可自动生成eni文件，用户只需获取pdo操作地址，注册周期任务即可，极大降低用户使用Ethercat主站难度。
开发环境要求
| 操作系统 | Ubuntu 20.04 LTS |
|---|---|
| 系统架构 | x86_64 |
| 编译器 | GCC version 9.4.0/GLIBC 2.31-0ubuntu9.2 GCC version 4.8.2/EGLIBC 2.19-0ubuntu6.15 |
| 依赖库 | Libpthread、librt、libdl、libm |
| --- | --- |
函数库API说明
使用概述
1. 将 libNexIghEcm.a 静态库文件复制到项目的 lib 目录
2.将 EcMasterApi.h 头文件复制到项目的 include 目录
3.在编译时链接 libNexIghEcm.a 库
NexIghLib API 函数列表
| 函数名称 | 函数功能 |
|---|---|
| startEcMaster | 开始启动主站 |
| enableRealtimeEnvironment | 使能实时环境 |
| ECM_LogMsg | 主站提供的消息级log打印 |
| ECM_LogError | 主站提供的错误级log打印 |
| ecatGetConnectedSlavesNum | 连接到主站的从站数目 |
| ecatGetConfiguredSlavesNum | 主站配置的从站数目 |
| ecatGetSlaveState | 获取从站的状态 |
| ecatSetSDO | 设置SDO |
| ecatGetSDO | 获取SDO |
| setEcatLicenseKey | 设置主站密钥（空函数，无作用） |
| isEcatLicenseCorrect | 获取主站密钥是否正确 |
| setLogDirName | 设置主站log输出的目录 |
| setEcatLogSwitch | 设置主站log是否开启 |
| getCycleTime | 获取主站实时性状态 |
| getEcLibVersion | 获取主站库版本 |
| getEniFileName | 获取eni文件名 |
| getPDOAddrVec | 获取从站pdo数据列表 |
| getSlaveIDVec | 获取从站ID、code列表 |
| registerCustomeContrastID | 注册主站是否完成的回调函数 |
| registerCustomeAppWorkpd | 注册比较主站找到的从站ID和预设从站ID是否相同的回调函数 |
| registerCustomeEcMasterStartFinish | 注册主站每周期调用的回调函数 |
| registerCustomeAppLog | 注册将主站log打印到nex日志中的回调函数 |
错误码定义
| 错误码 | 含义 |
|---|---|
| 0 | 无错误 |
| 1 | 总线忙状态 |
| 2 | 总线正在被使用 |
| 3 | 总线错误 |
| 4 | 设备访问超时 |
| 5 | IO 设备无法访问 |
| 6 | 参数不合法 |
| 7 | 文件加载错误 |
| 8 | 动态库加载错误 |
| 9 | EtherCAT 主机请求错误 |
| 10 | 获取从站数量时出错 |
| 11 | EtherCAT 主机获取从站失败 |
| 12 | XML 文件打开失败 |
| 13 | XML 信息解析失败 |
| 14 | 从站配置数据初始化失败 |
| 15 | 创建 EtherCAT 域失败 |
| 16 | 配置从站时出错 |
| 17 | 配置从站的 PDO 时出错 |
| 18 | 配置从站的 PDO 时出错 |
| 19 | 选择 EtherCAT 主机参考时钟时出错 |
| 20 | 配置从站 Sync0 信号时出错 |
| 21 | 主机激活失败 |
| 22 | 域数据错误 |
| 23 | 域大小错误 |
| 24 | 获取 EtherCAT PDO 时出错 |
基础数据类型
| typedef unsigned char EC_T_BYTE; |
|---|
| typedef unsigned short EC_T_WORD; |
| typedef unsigned int EC_T_DWORD; |
| typedef signed char EC_T_SBYTE; |
| typedef signed short EC_T_SWORD; |
| typedef signed int EC_T_SDWORD; |
| typedef double EC_T_REAL; |
pdo数据结构
功能描述
PDOAddrData结构体是PDO地址的结构体，一个结构体表示一个PDO地址对象。
结构体原型
typedef struct {
EC_T_WORD index;
EC_T_WORD subIndex;
EC_T_BYTE* addrMap;
} PDOAddrData;成员变量说明
| 变量名 | 描述 |
|---|---|
| Index | PDO索引 |
| subIndex | PDO子索引 |
| addrMap | PDO对象地址指针 |
NexIghLib API使用流程
使用示例
Demo.cpp
int CALLBACK()
{
static int iState = -5000;
if (iState < 3001)
{
ctrlwdSend(iState);
iState++;
}
else
{
for (int i = 0; i < slave_num; i++)
{
if (target_position[i] != nullptr)
{
iPos[i] += 300;
*target_position[i] = iPos[i];
}
}
}
return 0;
}
void myprintf(unsigned char c1, const char *s1, const char *s2, const char *s3, const long n, const char *format, ...)
{
char dest[1024 * 16 * 16];
va_list argptr;
va_start(argptr, format);
vsprintf(dest, format, argptr);
va_end(argptr);
printf(dest);
}
int main()
{
//初始化参数
int nArgc = 1;
char *argv[8];
int CycleTime = 1000;
argv[0]=(char *)(&CycleTime);
//使能实时环境
enableRealtimeEnvironment();
//注册日志回调
EC_PF_EC_START_CustomeLog_CALLBACK p2 = myprintf;
registerCustomeAppLog(p2);
//启动主站
startEcMaster(nArgc,argv);
//获取从站数量
slave_num = ecatGetConnectedSlavesNum();
printf("getSlaveIDVec\n");
//获取从站id数组
std::vector<std::pair<unsigned int, unsigned int> > vectorID;
getSlaveIDVec(vectorID);
//获取PDO地址映射
printf("getPDOAddrVec\n");
PDOAddrVec outPDOAddrVec, inPDOAddrVec;
getPDOAddrVec(outPDOAddrVec, inPDOAddrVec);
//访问输出PDO
for (unsigned int i = 0; i < outPDOAddrVec.size(); i++) {
for (unsigned int j = 0; j < outPDOAddrVec[i].size(); j++) {
if ((outPDOAddrVec[i][j].index == 0x6040)
&& (outPDOAddrVec[i][j].subIndex == 0x00)) {
control_word[i] = (EC_T_WORD*) (outPDOAddrVec[i][j].addrMap);
printf("get slave %d control_word addr = %x\n", i, control_word[i]);
}
}
}
//访问输入PDO
for (unsigned int i = 0; i < inPDOAddrVec.size(); i++) {
for (unsigned int j = 0; j < inPDOAddrVec[i].size(); j++) {
if ((inPDOAddrVec[i][j].index == 0x6041)
&& (inPDOAddrVec[i][j].subIndex == 0x00)) {
status_word[i] = (EC_T_WORD*) (inPDOAddrVec[i][j].addrMap);
printf("get slave %d status_word addr = %x\n", i, status_word[i]);
}
}
}
//注册自定义
printf("registerCustomeAppWorkpd\n");
EC_PF_EC_START_AppWorkpd_CALLBACK p = CALLBACK;
registerCustomeAppWorkpd(p);
while(1)
{
//自定义事件循环
}
return 0;
}MakeFile
#说明编译器
CXX ?= g++
CFLAGS = -std=c++11
#添加libNexIghEcm.a的依赖
LDFLAGS = -lm -ldl -lpthread -lrt
INCLUDE = -I.
#链接 ../目录下的libNexIghEcm.a
LIB = -L.. -lNexIghEcm
OBJ += $(patsubst %.cpp, %.o, $(wildcard *.cpp))
target = test
all:$(OBJ)
$(CXX) *.o -o $(target) $(LIB) $(LDFLAGS)
%.o:%.cpp
$(CXX) $(CFLAGS) -c $< -o $@ $(INCLUDE)
clean:
rm -rf *.o $(target)NexIghLib Api详解
startEcMaster
| 函数原型 | int startEcMaster(); |
|---|---|
| 功能描述 | 启动EtherCAT主站。 |
| 参数说明 | 无 |
| 返回值 | 返回 int 类型的值，0表示成功，非0表示失败。 |
| 备注说明 | 无 |
enableRealtimeEnvironment
| 函数原型 | int enableRealtimeEnvironment(); |
|---|---|
| 功能描述 | 启用实时环境。 |
| 参数说明 | 无 |
| 返回值 | 返回 int 类型的值，0表示成功，非0表示失败。 |
| 备注说明 | 此函数用于启用实时环境，以便主站能够在实时系统中运行。 |
ECM_LogMsg
| 函数原型 | void ECM_LogMsg(const char* msg); |
|---|---|
| 功能描述 | 记录日志消息。 |
| 参数说明 | 输入参数： msg：要记录的日志消息，类型为 const char*。 |
| 返回值 | 无 |
| 备注说明 | 该函数用于记录常规的日志消息。可以在系统中用于调试和运行时跟踪。 |
ECM_LogError
| 函数原型 | void ECM_LogError(const char* errorMsg); |
|---|---|
| 功能描述 | 记录错误日志。 |
| 参数说明 | 输入参数： errorMsg：要记录的错误消息，类型为 const char*。 |
| 返回值 | 无 |
| 备注说明 | 该函数用于记录错误日志。适用于记录程序运行时出现的错误信息。 |
ecatGetConnectedSlavesNum
| 函数原型 | int ecatGetConnectedSlavesNum(); |
|---|---|
| 功能描述 | 获取与主站连接的从站数量。 |
| 参数说明 | 无 |
| 返回值 | 返回 int 类型的值，表示已连接的从站数量。 |
| 备注说明 | 该函数用于获取与主站成功连接的从站的数量。 |
ecatGetConfiguredSlavesNum
| 函数原型 | int ecatGetConfiguredSlavesNum(); |
|---|---|
| 功能描述 | 获取配置的从站数量。 |
| 参数说明 | 无 |
| 返回值 | 返回 int 类型的值，表示配置的从站数量。 |
| 备注说明 | 无 |
ecatGetSlaveState
| 函数原型 | EC_T_WORD ecatGetSlaveState(EC_T_DWORD ecSlaveNum); |
|---|---|
| 功能描述 | 获取指定从站的状态。 |
| 参数说明 | 输入参数： ecSlaveNum：从站编号，从0开始。 |
| 返回值 | 从站的状态，类型为 EC_T_WORD。 |
| 备注说明 | 该函数用于获取指定从站的状态信息。 |
ecatSetSDO
| 函数原型 | int ecatSetSDO(EC_T_DWORD slaveNum, EC_T_WORD index, EC_T_DWORD subindex, EC_T_BYTE* value, EC_T_DWORD size); |
|---|---|
| 功能描述 | 设置从站的SDO值。 |
| 参数说明 | 输入参数： slaveNum：从站编号。 index：SDO的索引。 subindex：SDO的子索引。 value：要设置的SDO数据值。 size：数据值的大小。 |
| 返回值 | 返回 int 类型的值，0表示成功，非0表示失败。 |
| 备注说明 | 无 |
ecatGetSDO
| 函数原型 | int ecatGetSDO(EC_T_DWORD slaveNum, EC_T_WORD index, EC_T_DWORD subindex, EC_T_BYTE* value, EC_T_DWORD size, int num = 0); |
|---|---|
| 功能描述 | 获取从站的SDO值。 |
| 参数说明 | 输入参数： slaveNum：从站编号。 index：SDO的索引。 subindex：SDO的子索引。 value：用于存储SDO值的缓冲区。 size：缓冲区的大小。 num：可选参数，默认为0，表示要获取的SDO数据的数量。 输出参数： value：接收到的SDO数据值。 |
| 返回值 | 返回 int 类型的值，0表示成功，非0表示失败。 |
| --- | --- |
| 备注说明 | 该函数用于获取从站的SDO值。 |
setEcatLicenseKey
| 函数原型 | void setEcatLicenseKey(const char* licenseKey); |
|---|---|
| 功能描述 | 设置EtherCAT许可证密钥。 |
| 参数说明 | 输入参数： licenseKey：EtherCAT许可证密钥，类型为 const char* |
| 返回值 | 无 |
| 备注说明 | 无作用空函数 |
isEcatLicenseCorrect
| 函数原型 | bool isEcatLicenseCorrect(); |
|---|---|
| 功能描述 | 检查EtherCAT许可证是否有效。 |
| 参数说明 | 无 |
| 返回值 | 无 |
| 备注说明 | 无作用空函数 |
setLogDirName
| 函数原型 | void setLogDirName(const char* dir); |
|---|---|
| 功能描述 | 设置日志输出目录。 |
| 参数说明 | 输入参数： dir：日志目录路径，类型为 const char*。 |
| 返回值 | 无 |
| 备注说明 | 该函数用于设置日志文件的输出目录。 |
setEcatLogSwitch
| 函数原型 | void setEcatLogSwitch(bool enable); |
|---|---|
| 功能描述 | 设置EtherCAT日志开关。 |
| 参数说明 | 输入参数： enable：布尔值，true 表示启用日志记录，false 表示禁用日志记录。 |
| 返回值 | 无 |
| 备注说明 | 该函数用于启用或禁用EtherCAT的日志记录功能。 |
getCycleTime
| 函数原型 | CycleTime getCycleTime(); |
|---|---|
| 功能描述 | 获取主站的实时性周期时间。 |
| 参数说明 | 无 |
| 返回值 | CycleTime 类型，表示周期时间。 |
| 备注说明 | 此函数用于获取主站的实时性周期时间。 |
getEcLibVersion
| 函数原型 | const char* getEcLibVersion(); |
|---|---|
| 功能描述 | 获取EtherCAT库的版本号。 |
| 参数说明 | 无 |
| 返回值 | const char*，表示EtherCAT库的版本号。 |
| 备注说明 | 无 |
getEniFileName
| 函数原型 | const char* getEniFileName(); |
|---|---|
| 功能描述 | 获取配置的ENI文件名。 |
| 参数说明 | 无 |
| 返回值 | const char*，表示配置的ENI文件名。 |
| 备注说明 | 该函数用于获取当前配置的ENI文件名。 |
getPDOAddrVec
| 函数原型 | const std::vector<EC_T_DWORD>& getPDOAddrVec(); |
|---|---|
| 功能描述 | 获取PDO地址向量。 |
| 参数说明 | 无 |
| 返回值 | 返回 PDO 地址向量的引用，表示与主站通信的PDO地址。 |
| 备注说明 | 该函数用于获取主站和从站之间的PDO地址信息。 |
getSlaveIDVec
| 函数原型 | const std::vector<EC_T_DWORD>& getSlaveIDVec(); |
|---|---|
| 功能描述 | 获取从站的ID向量。 |
| 参数说明 | 无 |
| 返回值 | std::vector<EC_T_DWORD> 类型，表示从站的ID向量。 |
| 备注说明 | 该函数用于获取当前网络中所有从站的ID。 |
registerCustomeContrastID
| 函数原型 | void registerCustomeContrastID(void (*callback)(EC_T_DWORD slaveNum, bool isMatched)); |
|---|---|
| 功能描述 | 注册自定义对比ID的回调函数。 |
| 参数说明 | 输入参数： callback：回调函数，接受两个参数： slaveNum：从站编号。 isMatched：布尔值，表示从站ID是否与预设ID匹配。 |
| 返回值 | 无 |
| 备注说明 | 该函数用于注册一个回调函数，该函数将在主站检查从站ID与预设ID是否匹配时调用。 |
registerCustomeAppWorkpd
| 函数原型 | void registerCustomeAppWorkpd(void (*callback)(EC_T_DWORD slaveNum, bool isMatched)); |
|---|---|
| 功能描述 | 注册自定义工作周期回调函数。 |
| 参数说明 | 输入参数： callback：回调函数，接受两个参数： slaveNum：从站编号。 isMatched：布尔值，表示从站ID是否与预设ID匹配。 |
| 返回值 | 无 |
| 备注说明 | 该函数用于注册工作周期的回调函数。 |
registerCustomeEcMasterStartFinish
| 函数原型 | void registerCustomeEcMasterStartFinish(void (*callback)(bool success)); |
|---|---|
| 功能描述 | 注册自定义EtherCAT主站启动完成回调函数。 |
| 参数说明 | 输入参数： callback：回调函数，接受一个布尔值 success，表示启动是否成功。 |
| 返回值 | 无 |
| 备注说明 | 该函数用于注册工作周期的回调函数。 |
registerCustomeAppLog
| 函数原型 | void registerCustomeAppLog(void (callback)(const char logMessage)); |
|---|---|
| 功能描述 | 注册应用日志回调函数。 |
| 参数说明 | 输入参数： callback：回调函数，接受一个字符串 logMessage，表示日志信息。 |
| 返回值 | 无 |
| 备注说明 | 该函数用于注册自定义日志回调函数。 |