마스터 스테이션 라이브러리

소개

INEXBOT EtherCAT 마스터 컨트롤러의 마스터 지터 시간은 20us 미만입니다. 산업 자동화 제어 시스템 개발에 폭넓게 사용될 수 있으며, 특히 로봇, 서보 모터 제어 등 실시간성이 요구되는 시나리오에 적합합니다.

버전 정보

이차 개발 버전	회사
1.0.0	INEXBOT

버전 업데이트 이력

버전	수정 일자	수정자	설명
1.0.0	20250310	EA	초기 버전

개요

문서 소개

본 문서는 사용자가 INEXBOT EtherCAT의 마스터 제어용 C++ 라이브러리인 libNexIghEcm을 사용하는 것을 돕기 위해 작성되었습니다.

libNexIghEcm 라이브러리 소개

해당 라이브러리는 eni 파일을 자동으로 생성할 수 있으며, 사용자는 pdo 조작 주소를 가져오고 주기 작업을 등록하기만 하면 되어, 사용자가 EtherCAT 마스터를 사용하는 난이도를 크게 낮춥니다.

개발 환경 요구 사항

운영 체제	Ubuntu 20.04 LTS
시스템 아키텍처	x86_64
컴파일러	GCC version 9.4.0/GLIBC 2.31-0ubuntu9.2`<br>`GCC version 4.8.2/EGLIBC 2.19-0ubuntu6.15
의존성 라이브러리	Libpthread、librt、libdl、libm

| --- | --- |

함수 라이브러리 API 설명

사용 개요

정적 라이브러리 파일 libNexIghEcm.a를 프로젝트의 lib 디렉터리에 복사합니다.
EcMasterApi.h 헤더 파일을 프로젝트의 include 디렉터리에 복사합니다.
컴파일 시 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 사용 흐름

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);
기능 설명	로그 메시지를 기록합니다.
파라미터 설명	입력 파라미터:`<br>`msg: 기록할 로그 메시지, 타입은 const char*.
반환값	없음
비고	이 함수는 일반 로그 메시지를 기록하는 데 사용됩니다. 시스템에서 디버깅 및 런타임 추적에 사용할 수 있습니다.

ECM_LogError

함수 프로토타입	void ECM_LogError(const char* errorMsg);
기능 설명	오류 로그를 기록합니다.
파라미터 설명	입력 파라미터:`<br>`errorMsg: 기록할 오류 메시지, 타입은 const char*.
반환값	없음
비고	이 함수는 오류 로그를 기록하는 데 사용됩니다. 프로그램 실행 중 발생하는 오류 정보를 기록하는 데 적합합니다.

ecatGetConnectedSlavesNum

함수 프로토타입	int ecatGetConnectedSlavesNum();
기능 설명	마스터에 연결된 슬레이브 수를 가져옵니다.
파라미터 설명	없음
반환값	int 타입 값을 반환하며, 연결된 슬레이브 수를 나타냅니다.
비고	이 함수는 마스터에 성공적으로 연결된 슬레이브 수를 가져오는 데 사용됩니다.

ecatGetConfiguredSlavesNum

함수 프로토타입	int ecatGetConfiguredSlavesNum();
기능 설명	구성된 슬레이브 수를 가져옵니다.
파라미터 설명	없음
반환값	int 타입 값을 반환하며, 구성된 슬레이브 수를 나타냅니다.
비고	없음

ecatGetSlaveState

함수 프로토타입	EC_T_WORD ecatGetSlaveState(EC_T_DWORD ecSlaveNum);
기능 설명	지정된 슬레이브의 상태를 가져옵니다.
파라미터 설명	입력 파라미터:`<br>`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 값을 설정합니다.
파라미터 설명	입력 파라미터:`<br>`slaveNum: 슬레이브 번호.`<br>`index: SDO 인덱스.`<br>`subindex: SDO 서브 인덱스.`<br>`value: 설정할 SDO 데이터 값.`<br>`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 값을 가져옵니다.
파라미터 설명	입력 파라미터:`<br>`slaveNum: 슬레이브 번호.`<br>`index: SDO 인덱스.`<br>`subindex: SDO 서브 인덱스.`<br>`value: SDO 값을 저장할 버퍼.`<br>`size: 버퍼 크기.`<br>`num: 선택적 파라미터, 기본값 0, 가져올 SDO 데이터의 수량.`<br>`출력 파라미터:`<br>`value: 수신된 SDO 데이터 값.
반환값	int 타입 값을 반환하며, 0은 성공, 0이 아닌 값은 실패를 나타냅니다.
---	---
비고	이 함수는 슬레이브의 SDO 값을 가져오는 데 사용됩니다.

setEcatLicenseKey

함수 프로토타입	void setEcatLicenseKey(const char* licenseKey);
기능 설명	EtherCAT 라이선스 키를 설정합니다.
파라미터 설명	입력 파라미터:`<br>`licenseKey: EtherCAT 라이선스 키, 타입은 const char*.
반환값	없음
비고	동작 없는 빈 함수

isEcatLicenseCorrect

함수 프로토타입	bool isEcatLicenseCorrect();
기능 설명	EtherCAT 라이선스가 유효한지 확인합니다.
파라미터 설명	없음
반환값	없음
비고	동작 없는 빈 함수

setLogDirName

함수 프로토타입	void setLogDirName(const char* dir);
기능 설명	로그 출력 디렉터리를 설정합니다.
파라미터 설명	입력 파라미터:`<br>`dir: 로그 디렉터리 경로, 타입은 const char*.
반환값	없음
비고	이 함수는 로그 파일의 출력 디렉터리를 설정하는 데 사용됩니다.

setEcatLogSwitch

함수 프로토타입	void setEcatLogSwitch(bool enable);
기능 설명	EtherCAT 로그 스위치를 설정합니다.
파라미터 설명	입력 파라미터:`<br>`enable: bool 값, 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 대조 콜백 함수를 등록합니다.
파라미터 설명	입력 파라미터:`<br>`callback: 콜백 함수, 두 개의 파라미터를 받음:`<br>`slaveNum: 슬레이브 번호.`<br>`isMatched: bool 값, 슬레이브 ID가 사전 설정된 ID와 일치하는지 여부를 나타냅니다.
반환값	없음
비고	이 함수는 콜백 함수를 등록하는 데 사용되며, 해당 함수는 마스터가 슬레이브 ID와 사전 설정 ID가 일치하는지 검사할 때 호출됩니다.

registerCustomeAppWorkpd

함수 프로토타입	void registerCustomeAppWorkpd(void (*callback)(EC_T_DWORD slaveNum, bool isMatched));
기능 설명	사용자 정의 워크 사이클 콜백 함수를 등록합니다.
파라미터 설명	입력 파라미터:`<br>`callback: 콜백 함수, 두 개의 파라미터를 받음:`<br>`slaveNum: 슬레이브 번호.`<br>`isMatched: bool 값, 슬레이브 ID가 사전 설정된 ID와 일치하는지 여부를 나타냅니다.
반환값	없음
비고	이 함수는 워크 사이클의 콜백 함수를 등록하는 데 사용됩니다.

registerCustomeEcMasterStartFinish

함수 프로토타입	void registerCustomeEcMasterStartFinish(void (*callback)(bool success));
기능 설명	사용자 정의 EtherCAT 마스터 시작 완료 콜백 함수를 등록합니다.
파라미터 설명	입력 파라미터:`<br>`callback: 콜백 함수, bool 값 success를 받아 시작 성공 여부를 나타냅니다.
반환값	없음
비고	이 함수는 워크 사이클의 콜백 함수를 등록하는 데 사용됩니다.

registerCustomeAppLog

함수 프로토타입	void registerCustomeAppLog(void (callback)(const char logMessage));
기능 설명	애플리케이션 로그 콜백 함수를 등록합니다.
파라미터 설명	입력 파라미터:`<br>`callback: 콜백 함수, 문자열 logMessage를 받아 로그 정보를 나타냅니다.
반환값	없음
비고	이 함수는 사용자 정의 로그 콜백 함수를 등록하는 데 사용됩니다.

01.사용자-정의-명령어

01.티치-펜던트-구현

02.컨트롤러-구현

01.시작하기

03.API-예제

01.기본-응용

02.고급-응용

01.시작하기

02.API-예제

01.시작하기

02.API-예제

01.기본-응용

02.고급-응용

02.6000-포트-통신

01.모션-제어

02.상태-제어

03.프로세스

06.레이저-절단

04.작업-파일

05.외부-제어

06.기타

01.시스템

02.로봇

01.매개변수

03.프로그램

02.명령어-CRUD

04.주변기기-통신

05.프로세스

마스터 스테이션 라이브러리 ​

소개 ​

버전 정보 ​

버전 업데이트 이력 ​

개요 ​

문서 소개 ​

libNexIghEcm 라이브러리 소개 ​

개발 환경 요구 사항 ​

함수 라이브러리 API 설명 ​

사용 개요 ​

NexIghLib API 함수 목록 ​

오류 코드 정의 ​

기본 데이터 타입 ​

pdo 데이터 구조 ​

기능 설명 ​

구조체 프로토타입 ​

멤버 변수 설명 ​

NexIghLib API 사용 흐름 ​

사용 예시 ​

Demo.cpp ​

MakeFile ​

NexIghLib Api 상세 설명 ​

startEcMaster ​

enableRealtimeEnvironment ​

ECM_LogMsg ​

ECM_LogError ​

ecatGetConnectedSlavesNum ​

ecatGetConfiguredSlavesNum ​

ecatGetSlaveState ​

ecatSetSDO ​

ecatGetSDO ​

setEcatLicenseKey ​

isEcatLicenseCorrect ​

setLogDirName ​

setEcatLogSwitch ​

getCycleTime ​

getEcLibVersion ​

getEniFileName ​

getPDOAddrVec ​

getSlaveIDVec ​

registerCustomeContrastID ​

registerCustomeAppWorkpd ​

registerCustomeEcMasterStartFinish ​

registerCustomeAppLog ​

마스터 스테이션 라이브러리

소개

버전 정보

버전 업데이트 이력

개요

문서 소개

libNexIghEcm 라이브러리 소개

개발 환경 요구 사항

함수 라이브러리 API 설명

사용 개요

NexIghLib API 함수 목록

오류 코드 정의

기본 데이터 타입

pdo 데이터 구조

기능 설명

구조체 프로토타입

멤버 변수 설명

NexIghLib API 사용 흐름

사용 예시

Demo.cpp

MakeFile

NexIghLib Api 상세 설명

startEcMaster

enableRealtimeEnvironment

ECM_LogMsg

ECM_LogError

ecatGetConnectedSlavesNum

ecatGetConfiguredSlavesNum

ecatGetSlaveState

ecatSetSDO

ecatGetSDO

setEcatLicenseKey

isEcatLicenseCorrect

setLogDirName

setEcatLogSwitch

getCycleTime

getEcLibVersion

getEniFileName

getPDOAddrVec

getSlaveIDVec

registerCustomeContrastID

registerCustomeAppWorkpd

registerCustomeEcMasterStartFinish

registerCustomeAppLog