엣지 연동 가이드

Bridge.Host에서 설비를 구성하고, Engine과 mDNS로 자동 연동하여, AAS(Asset Administration Shell) 디지털 트윈을 생성하는 전체 과정을 안내합니다.

📋 사전 요구사항

항목	포트	역할
Caffeine Engine	5001 (HTTP), 5050 (gRPC)	중앙 서버
Caffeine Admin	5233	관리 대시보드
Caffeine Bridge.Host	5100	엣지 게이트웨이
Redis	6379	캐시/스트림
MQTT Broker	1883	메시지 브로커

Caffeine CLI 설치

cafe 명령어를 사용하려면 CLI를 먼저 설치하세요:

dotnet tool install -g NEXCODE.Caffeine.Cli
cafe --version

이미 설치된 경우 업데이트: dotnet tool update -g NEXCODE.Caffeine.Cli

# 배포 파일 추출 (최초 1회)
cafe setup extract

# Caffeine 서비스 시작 (Engine + Admin + Bridge.Host + 인프라)
cafe setup
# 프로파일 선택: app

# 서비스 상태 확인
cafe setup status

🚀 Step 1: Bridge.Host 최초 설정

Bridge.Host를 처음 실행하면 First-Run Setup 화면이 표시됩니다.

브라우저에서 http://localhost:5100 접속
관리자 비밀번호 설정 (4자 이상)
"설정 완료" 클릭 → 로그인 화면으로 전환
admin / 설정한 비밀번호로 로그인

🔧 Step 2: 설비 정보 등록

로그인 후 설비 정보 탭에서 엣지 장비의 기본 정보를 입력합니다.

설비 정보 등록

필드	예시	설명
설비명	`CNC-Pump-01`	장비 고유 식별 이름
카테고리	`Pump`	장비 유형 (Pump/Motor/Conveyor/Robot/CNC/PLC/Sensor/Other)
위치	`2F-Line3-Bay5`	설비 물리적 위치 (층-라인-베이)

저장 버튼을 클릭하면 "설비 정보 저장됨" 토스트가 표시됩니다.

설비명 규칙

설비명은 {카테고리}-{용도}-{번호} 형식을 권장합니다. 이 이름이 AAS Shell의 IdShort로 사용됩니다.

🏷️ Step 3: 태그(Tag) 등록

태그 관리 탭에서 수집할 센서 데이터 포인트를 등록합니다.

태그 추가

+ 태그 추가 버튼 클릭
태그 정보 입력

태그 추가 모달

필드	예시	설명
이름	`Temperature_01`	태그 고유 이름
주소	`D100`	드라이버별 메모리 주소 (Modbus: 레지스터, PLC: 디바이스 주소)
데이터 타입	`Float`	Int16, Int32, Float, Double, Bool, String
센서 속성	`Temperature`	센서 물리량 (AAS Submodel 매핑에 사용)
스캔 주기(ms)	`500`	데이터 수집 간격 (ms)

추가 클릭

등록된 태그 확인

여러 태그를 등록하면 테이블에서 편집/삭제가 가능합니다.

태그 목록

Community 라이선스 제한

Community(무료) 라이선스에서는 최대 50개 태그까지 등록할 수 있습니다. Professional 라이선스로 업그레이드하면 제한이 해제됩니다.

🔌 Step 4: 드라이버 설정

드라이버 탭에서 장비 통신 프로토콜을 설정합니다.

드라이버 유형	용도	설정
Simulation	테스트용 가상 드라이버	IP/포트 불필요
ModbusTcp	Modbus TCP 장비	IP + 포트(502)
ModbusRtu	Modbus RTU (시리얼)	COM 포트 + 보드레이트
OmronFins	Omron PLC (FINS)	IP + 포트(9600)
MitsubishiSlmp	Mitsubishi PLC (SLMP)	IP + 포트(5000)

개발/테스트 시에는 Simulation 드라이버를 선택하면 실제 장비 없이 데이터가 생성됩니다.

🌐 Step 5: Engine에서 Bridge 검색 (mDNS Discovery)

Admin 대시보드에서 네트워크의 Bridge.Host를 자동으로 검색합니다.

Admin (http://localhost:5233) 로그인
좌측 메뉴 → 드라이버 및 통신 → Bridge Discovery 또는 URL 직접 접속: /bridge-discovery

Bridge Discovery

스캔 버튼 클릭 → 같은 네트워크의 Bridge.Host가 자동 감지됩니다

상태	설명
검색됨	mDNS로 발견된 Bridge 수
미바인딩	아직 Engine에 등록되지 않은 Bridge
바인딩됨	Engine에 등록 완료된 Bridge
온라인	현재 연결 활성 상태인 Bridge

mDNS가 동작하지 않을 때

같은 머신에서 실행하는 경우 mDNS 데몬(Bonjour/Avahi)이 설치되지 않으면 자동 검색이 안 될 수 있습니다. 이 경우 Bridge.Host의 REST API(http://localhost:5100/api/bridge/status)를 통해 수동으로 등록할 수 있습니다.

🌐 Step 6: AAS (Asset Administration Shell) 확인

Bridge에서 등록한 설비 정보는 AAS Shell로 변환되어 Admin에서 조회할 수 있습니다.

Admin → /aas 접속

AAS Shell Viewer

등록된 AAS Shell 목록에서 설비를 선택하면:
- Nameplate Submodel: 설비 기본 정보 (제조사, 모델, 위치)
- TechnicalData Submodel: 기술 사양
- OperationalData Submodel: 실시간 운영 데이터 (태그 값)
- AlarmCondition Submodel: 알람 상태

AAS가 비어있을 때

"등록된 AAS가 없습니다"라고 표시되면:

Bridge.Host가 실행 중인지 확인
Engine과의 gRPC 연결 상태 확인 (Bridge 콘솔에서 [GrpcTransport] 연결 완료 메시지)
AASX 파일을 직접 임포트하려면 /aas/import 페이지 사용

📊 Step 7: 감사 로그 확인

Bridge.Host의 감사 로그 탭에서 모든 작업 이력을 확인할 수 있습니다.

감사 로그

작업	설명
SETUP	최초 설정 완료
LOGIN	관리자 로그인
UPDATE	설비/드라이버 설정 변경
CREATE	태그 추가
DELETE	태그 삭제
LICENSE_ACTIVATE	라이선스 활성화

📄 라이선스 관리

Community vs Professional

항목	Community (무료)	Professional
최대 태그	50개	무제한
최대 드라이버	1개	무제한
허용 서브모델	3종	7종
감사 로그	비활성	활성

Professional 활성화

PKV(Partial Key Verification) 키가 있으면:

# Bridge.Host API로 활성화
curl -X POST http://localhost:5100/api/bridge/license/activate \
  -H "Content-Type: application/json" \
  -b "bridge_session=YOUR_SESSION_TOKEN" \
  -d '{"key": "YOUR-PKV-KEY"}'

Community로 다운그레이드

라이선스를 제거하면 자동으로 Community 모드로 전환됩니다. 50개 이상의 태그가 등록된 경우 초과분은 비활성화됩니다.

🔌 엣지 연동 끊기

Bridge.Host를 Engine에서 분리하려면:

Bridge.Host 프로세스 종료 (Ctrl+C)
Admin → Bridge Discovery에서 해당 Bridge가 "오프라인"으로 표시됨
Engine은 자동으로 연결 재시도를 중단하고 graceful degradation

데이터 보존

Bridge.Host를 종료해도 로컬 설정(bridge_config.json)은 보존됩니다. 재시작하면 동일한 설비/태그 구성으로 자동 복구됩니다.

🔧 트러블슈팅

Bridge.Host가 Engine에 연결되지 않음

[GrpcTransport] 연결 중... http://localhost:5001
[GrpcTransport] raw 전송 실패 — Connection refused

확인사항:

Engine이 실행 중인지 확인: curl http://localhost:5001/health
Engine의 gRPC 포트(5050) 방화벽 확인
Bridge의 driver_settings.json에서 EngineUrl 확인

태그가 50개 제한에 걸림

Community 라이선스 제한입니다. Professional 키를 활성화하거나, 불필요한 태그를 삭제하세요.

mDNS 검색에 Bridge가 안 보임

macOS: Bonjour 기본 내장 (정상 동작)
Linux: avahi-daemon 설치 필요 (sudo apt install avahi-daemon)
Windows: Bonjour Print Services 설치 또는 수동 등록 사용

📚 다음 단계

시뮬레이션 환경 구성 가이드 — 가상 장비로 테스트
벤치마크 테스트 가이드 — 성능 측정
AAS 시작 가이드 — AAS 표준 상세

📋 사전 요구사항​

🚀 Step 1: Bridge.Host 최초 설정​

🔧 Step 2: 설비 정보 등록​

🏷️ Step 3: 태그(Tag) 등록​

태그 추가​

등록된 태그 확인​

🔌 Step 4: 드라이버 설정​

🌐 Step 5: Engine에서 Bridge 검색 (mDNS Discovery)​

🌐 Step 6: AAS (Asset Administration Shell) 확인​

📊 Step 7: 감사 로그 확인​

📄 라이선스 관리​

Community vs Professional​

Professional 활성화​

Community로 다운그레이드​

🔌 엣지 연동 끊기​

🔧 트러블슈팅​

Bridge.Host가 Engine에 연결되지 않음​

태그가 50개 제한에 걸림​

mDNS 검색에 Bridge가 안 보임​

📚 다음 단계​