메뉴얼 버전 1.0 | 모듈 버전(DLL) 1.0.2.9392 |

X-DAS RabbitMQ 프로토콜 매뉴얼

1. 소개 X-DAS RabbitMQ 프로토콜은 X-DAS 시스템과 RabbitMQ 메시지 브로커를 연동하기 위한 통신 모듈입니다. 주요 기능 RabbitMQ 큐(Queue)에서 데이터를 수신하여 X-DAS 태그에 반영 (구독) 태그 값을 RabbitMQ 큐에 전송 (발행) 하나의 연결로 여러 큐를 동시에 구독/발행 네트워크 장애 시 자동 재연결 큐 속성 충돌 시 자동 복구 (채널 재생성 + 블랙리스트)

Part A. Quick Start

이 장만 읽으면 기본적인 RabbitMQ 연동이 가능합니다.

2. Quick Start Guide

2.1 사전 준비

항목	준비
X-DAS	X-DAS 1.1.13 이상 설치
RabbitMQ 브로커	네트워크에서 접근 가능한 상태 (기본 포트: 5672)
필요 정보	브로커 IP, 포트, 접속 계정/비밀번호

2.2 Step 1: 디바이스 설정

RabbitMQ 프로토콜은 X-DAS 설치 시 함께 배포됩니다. 별도 파일 복사는 필요 없습니다.

1. Devices 우클릭 → New Device → New Other 탭

     

2. RabbitMQ Client 선택
   
   
   

3. 아래 4개 항목만 설정합니다 (나머지는 기본값 유지).

항목	입력값
HostName	192.168.1.100 (브로커 IP)
Port	5672 (기본값 유지)
UserName	guest (브로커 계정)
Password	guest (브로커 비밀번호)

2.3 Step 2: 태그 등록

1. 좌측트리의 Tags 클릭 → 태그 영역 우클릭 → New Tag
2. DeviceAddress에 RabbitMQ 큐 이름을 그대로 입력합니다.

Name	Address	AccessMode	DataType
TAG_온도	sensor_temp	Full	Float
TAG_습도	sensor_humidity	Read	Float
CMD_밸브	command_valve	Full	Float

DeviceAddress = 큐 이름입니다. 대소문자를 구분합니다. AccessMode: Full(기본값) = 읽기+쓰기, Read = 읽기 전용.

2.4 Step 3: 동작 확인

1. X-DAS Server를 시작합니다.
2. 태그 모니터에서 태그 값이 업데이트되는지 확인합니다.
3. Full 모드 태그에 값을 쓰고 RabbitMQ 큐에서 수신을 확인합니다.

2.5 문제 발생 시 확인 사항

증상	확인
연결 안됨	브로커가 실행 중인지, IP/포트가 맞는지 확인
인증 실패	UserName/Password 확인. guest 계정은 localhost만 허용되는 경우가 많음
값이 안 뜸	Address(큐 이름)가 정확한지 확인. 대소문자 구분됨

해결되지 않으면 아래 Part B의 8절 Troubleshooting을 참고하세요.

Part B. 상세 레퍼런스

고급 설정, 전체 프로퍼티 사양, 트러블슈팅이 필요할 때 참고합니다.

3. 구성

3.1 통신 모델

X-DAS RabbitMQ 프로토콜은 Publish/Subscribe 모델로 동작합니다.

• Full 모드 (기본값): 지정한 큐를 구독(Subscribe)하면서, 태그 값 변경 시 동일 큐에 발행(Publish)도 수행
• Read 모드: 지정한 큐를 구독만 수행. 태그에 값을 쓸 수 없음

하나의 디바이스(연결)에서 여러 큐를 동시에 구독/발행할 수 있습니다.

3.2 데이터 흐름

[구독 (Read)] RabbitMQ 큐 → 비동기 콜백 → 메시지 캐시 → SCADA 스캔 주기에 태그 반영 [발행 (Write)] 태그 값 변경 → 문자열 변환 → BasicPublish → RabbitMQ 큐

• 메시지는 UTF-8 텍스트 문자열로 전송되며, DataType에 맞게 자동 변환됩니다.
• 수신은 논블로킹(Non-blocking)으로 처리되어 SCADA 스캔 주기에 영향을 주지 않습니다.

3.3 주소 체계

모드	Address 형식	설명
기본 (권장)	sensor_temp	큐 이름 직접 입력. 기본 Exchange 사용.
확장	exchange=events;key=sensor.*;queue=sensor_q	Exchange 라우팅. 고급 사용.

4. 구성 파일

RabbitMQ 프로토콜은 X-DAS 인스톨러에 포함되어 자동 배포됩니다. 별도 설치 절차는 없습니다.

파일	설치 위치	설명
Xisom.DAS.Protocol.RabbitMQ.dll	Protocols\	프로토콜 모듈
RabbitMQ.Client.dll	Protocols\	AMQP 클라이언트 라이브러리 (6.8.1)
System.Threading.Channels.dll	Protocols\	RabbitMQ.Client 종속 라이브러리

5. 프로퍼티 레퍼런스

디바이스를 선택하면 속성 창에 5개 카테고리로 그룹화된 프로퍼티가 표시됩니다.

5.1 RabbitMQ Connection

항목	기본값	제한값	설명
HostName	localhost	문자열	브로커 IP 또는 도메인
Port	5672	1 ~ 65535	AMQP 통신 포트. TLS 시 5671
VirtualHost	/	문자열	가상 호스트 (환경 분리)
ClientName	(빈 값)	문자열	클라이언트 식별 이름 (비워두면 자동 생성)
ConnectionTimeout	30000	최소 1000 (ms)	연결 타임아웃
RequestedHeartbeat	60	최소 0 (초)	하트비트 간격 (0=비활성화)
AutomaticRecovery	True	True / False	네트워크 장애 시 자동 재연결

5.2 RabbitMQ Credential

항목	기본값	제한값	설명
UserName	guest	문자열	접속 계정
Password	guest	문자열	접속 비밀번호

guest 계정은 보안상 localhost 접속만 허용되는 경우가 많습니다. 원격 접속 시 별도 계정을 사용하세요.

5.3 RabbitMQ Queue

항목	기본값	제한값	설명
AutoCreateQueue	True	True / False	큐 자동 생성 여부
QueueDurable	True	True / False	브로커 재시작 시 큐 유지
QueueExclusive	False	True / False	독점 큐 (연결 종료 시 삭제)
QueueAutoDelete	False	True / False	마지막 소비자 해제 시 삭제

AutoCreateQueue 상세

값	동작
True (기본)	Read/Write 모두 큐가 없으면 자동 생성. 이미 있으면 기존 사용.
False	큐를 생성하지 않음. 브로커에 미리 존재해야 함. 없으면 Read는 Bad, Write는 메시지 드롭.

큐 속성 권장 조합

환경	Durable	Exclusive	AutoDelete
운영 (기본값)	True	False	False
테스트/개발	False	False	True
임시 전용 큐	False	True	True

5.4 RabbitMQ Message

항목	기본값	제한값	설명
ContentType	application/json	문자열	메시지 형식 메타 정보
MessagePersistent	True	True / False	메시지 디스크 저장
MessageTTL	0	최소 0 (ms)	메시지 유효 시간 (0=무제한)
PrefetchCount	10	최소 1	동시 처리 메시지 수 (QoS)

5.5 RabbitMQ Exchange

일반 사용에서는 변경하지 않아도 됩니다.

항목	기본값	제한값	설명
ExchangeName	(빈 값)	문자열	Exchange 이름 (빈 값 = 기본 Exchange)
ExchangeType	Direct	Direct / Topic / Fanout / Headers	라우팅 방식
ExchangeDurable	True	True / False	Exchange 영속성
PublishConfirm	False	True / False	발행 확인 (신뢰성↑, 성능↓)

6. 태그 설정 레퍼런스

태그를 등록할 때 아래 항목을 설정합니다.

항목	설명	입력 예시
Name	X-DAS에서 사용할 태그 이름	TAG_온도
Address	연동할 RabbitMQ 큐(Queue) 이름	sensor_temp
AccessMode	Full(기본값) = 읽기+쓰기, Read = 읽기 전용	Full
DataType	데이터 타입	Float

AccessMode 참고: X-DAS 태그의 기본 AccessMode는 Full입니다. Full 모드에서는 X-DAS 코어가 Read 사이클과 Write 사이클을 자동으로 분리하여 프로토콜에 전달합니다. 읽기만 필요한 센서 태그는 Read로 설정하면 Write가 차단됩니다.

6.1 Address 작성 규칙

기본 방식 (권장)

sensor_temp sensor_humidity command_valve

확장 방식 (Exchange 라우팅)

exchange=이름;key=라우팅키;queue=큐이름

예시

exchange=events;key=sensor.*;queue=sensor_queue

무효 예시

Address	문제
Sensor_Temp (대소문자 다름)	브로커의 sensor_temp와 다른 큐로 인식
exchange=logs;key=app.* (queue 생략)	Read 태그에서 구독 큐를 지정할 수 없음

6.2 AccessMode 유형별 동작

AccessMode	동작	설명
Full (기본값)	구독 + 발행	큐에서 메시지를 수신하여 태그 값을 갱신하면서, 태그 값 변경 시 동일 큐에 메시지를 발행합니다. X-DAS 코어가 Read/Write 사이클을 자동으로 분리하여 프로토콜에 전달합니다.
Read	구독 전용	큐에서 메시지를 수신만 합니다. 태그에 값을 쓸 수 없습니다.

Full 모드에서 AutoCreateQueue=True이면, Read 사이클 또는 Write 사이클 중 먼저 실행되는 쪽에서 큐를 자동 생성하며, 이후에는 중복 생성하지 않습니다.

6.3 지원 DataType

DataType	용도	메시지 예시
String	문자열	"운전중", "OK"
Float	실수 (32bit)	25.5
Double	실수 (64bit)	1013.25
Int32	정수 (32bit)	100, -5
Int16	정수 (16bit)	255
Bool	참/거짓	true, false

메시지는 UTF-8 텍스트로 전송되며 DataType에 맞게 자동 변환됩니다. 변환 실패 시 태그 상태가 Bad로 표시됩니다.

6.4 태그 구성 예시

예시 1: 센서 데이터 수신 (읽기 전용)

Name	Address	AccessMode	DataType
TAG_온도	sensor_temp	Read	Float
TAG_습도	sensor_humidity	Read	Float
TAG_기압	sensor_pressure	Read	Double
TAG_상태	device_status	Read	String

예시 2: 양방향 (수신 + 제어)

Name	Address	AccessMode	DataType
TAG_밸브개도	command_valve	Full	Float
TAG_운전모드	command_mode	Full	Int32
TAG_비상정지	command_estop	Full	Bool

Full 모드는 큐에서 값을 읽으면서, 태그에 값을 쓰면 동일 큐에 발행합니다.

예시 3: Exchange 라우팅

Name	Address	AccessMode	DataType
TAG_센서	exchange=events;key=sensor.temp;queue=sensor_q	Full	Float

7. 동작 확인

7.1 연결 확인

확인 항목	방법
디바이스 상태	X-DAS Server 시작 후 디바이스 상태가 "연결됨"으로 표시
Management UI	http://브로커IP:15672 → Connections 탭에서 X-DAS 연결 확인
채널 수	Channels 탭에서 Publish + Consume 채널 2개 표시

7.2 태그 값 확인

1. 태그 모니터에서 Read 태그 값이 업데이트되는지 확인
2. Management UI → Queues 탭에서 큐 목록, Consumer 수, 메시지 수 확인
3. Write 태그에 값을 쓰고 Management UI에서 메시지 도착 확인

8. 트러블슈팅

8.1 증상별 해결

증상	원인	해결
연결 안됨	브로커 미실행 또는 IP/포트 오류	브로커 실행 확인, HostName/Port 확인
인증 실패	잘못된 계정 또는 guest 원격 제한	UserName/Password 확인. 원격 시 별도 계정 사용
타임아웃	네트워크 문제 또는 방화벽	방화벽 5672 포트 허용 확인
연결 후 끊김	하트비트 미스매치	RequestedHeartbeat 값 확인, AutomaticRecovery=True 확인
값이 안 뜸	큐에 메시지가 없음	Management UI에서 큐 메시지 수 확인
Bad 상태	Address 오류 또는 타입 불일치	큐 이름 대소문자 확인, DataType과 메시지 형식 일치 확인
블랙리스트 로그	큐 속성 충돌 (PRECONDITION_FAILED)	아래 "큐 속성 충돌 복구" 참고

8.2 큐 속성 충돌 복구

브로커의 기존 큐와 X-DAS 설정(QueueDurable 등)이 다르면 에러가 발생합니다. 해당 큐는 블랙리스트에 등록되어 반복 에러를 방지합니다.

복구 절차

1. X-DAS 로그에서 Queue '큐이름' blacklisted 메시지 확인
2. 원인 해결
   • 방법 A: Management UI에서 해당 큐 삭제 → X-DAS가 올바른 속성으로 재생성
   • 방법 B: X-DAS의 큐 설정을 브로커 기존 큐에 맞춤
3. X-DAS Studio에서 디바이스 프로퍼티 저장 → 블랙리스트 자동 해제
4. 재시도 실패 시 다시 블랙리스트 등록 → 로그 재확인

X-DAS 재시작으로도 블랙리스트는 초기화됩니다.

9. 부록

9.1 FAQ

Q: 하나의 디바이스에 태그를 몇 개까지 등록할 수 있나요?

A: 제한 없습니다. 하나의 연결에서 여러 큐를 동시에 구독/발행합니다.

Q: 여러 RabbitMQ 브로커에 동시에 연결할 수 있나요?

A: 예. 디바이스를 브로커 수만큼 생성하면 됩니다.

Q: 브로커와 연결이 끊어지면?

A: AutomaticRecovery=True(기본값)이면 자동 재연결 후 구독이 복구됩니다.

Q: 메시지 포맷은?

A: UTF-8 텍스트 문자열. Float 25.5 → "25.5" 문자열로 전송/수신.

Q: Exchange 설정은 언제 사용하나요?

A: 대부분 불필요합니다. Topic/Fanout 등 고급 라우팅이 필요할 때만 사용합니다.

Q: 특정 큐 에러가 다른 큐에 영향을 주나요?

A: 에러 큐는 블랙리스트에 등록되어 건너뛰고, 정상 큐는 자동 복구됩니다.

Q: 블랙리스트를 재시작 없이 해제할 수 있나요?

A: 원인 해결 후 디바이스 프로퍼티를 저장하면 해제됩니다.

9.2 Data Type 레퍼런스

DataType	크기	범위	메시지 변환
Bool	1 bit	true / false	"true", "false"
Int16	16 bit	-32,768 ~ 32,767	"255"
Int32	32 bit	-2^31 ~ 2^31-1	"100"
Float	32 bit	±3.4×10^38	"25.5"
Double	64 bit	±1.7×10^308	"1013.25"
String	가변	UTF-8	그대로 전달

9.3 Address 형식 요약

모드	형식	예시
기본	큐이름	sensor_temp
확장	exchange=이름;key=키;queue=큐	exchange=events;key=sensor.*;queue=sensor_q