플로우 (Node-RED) — 시작하기

/ui/flow 메뉴를 통해 게이트웨이에 내장된 Node-RED 환경에 접속할 수 있습니다. Node-RED 는 블록(노드) 을 드래그-앤-드롭 으로 연결해 데이터 흐름을 만드는 로코드 툴 입니다. 게이트웨이의 태그값을 읽고 쓰고, MQTT/HTTP 로 외부 시스템과 연계하고, 알람·로깅·계산 같은 자동화를 그려낼 수 있습니다.

2026.05+ 컨테이너 모드의 Node-RED

Node-RED 4.1.10 + Node.js 20 (모두 image 안 global 설치). 컨테이너 첫 부팅 시 userDir.seed (image-baked 기본 flows + node_modules + plantpulse-edge / node-red-contrib-opcua 노드) 가 /data1/pp-data/node-userdir/ 로 자동 복사됩니다 (두 번째 부팅부터 사용자 flow 보존). image upgrade 후에도 사용자 flow 그대로.

플랜트펄스 전용 노드 (pp-tag-value-read / pp-tag-value-write / pp-opc-* / pp-tag-list) 는 image 의 node/conf/plantpulse-edge-nodes/ 를 절대경로 symlink 로 연결 — entrypoint 가 매 부팅 보장 (relative path 였던 옛 native 의 symlink 가 컨테이너에선 깨지는 이슈 사전 차단).

이 문서를 읽기 전에

자주 하는 작업 → 새 PLC 연결 추가 / 태그 등록 까지 끝내고 하나 이상의 태그가 실시간으로 수집되고 있는 상태 에서 시작하세요. Node-RED 는 그 태그값을 입력으로 사용합니다.

1. 접속

브라우저에서 게이트웨이 에 접속한 뒤 좌측 메뉴 플로우 (Node-RED) 또는 직접 http://<게이트웨이>/ui/flow 로 이동합니다.

2. 화면 구성

영역	설명
좌측 팔레트	사용할 수 있는 노드 목록. 카테고리별로 정렬됩니다. `엣지` 카테고리에 게이트웨이 전용 노드가 들어 있습니다.
가운데 워크스페이스	노드를 드래그해 배치하고 와이어로 연결합니다. 탭(여러 플로우) 단위로 분리할 수 있습니다.
우측 사이드바	`info` 탭에서 선택한 노드의 도움말, `debug` 탭에서 `debug` 노드 출력 로그가 보입니다.
우상단 Deploy	변경 사항을 실제로 동작시키려면 반드시 Deploy 버튼을 눌러야 합니다.

3. 기본 조작 — 알아두면 편한 단축키

동작	방법
노드 추가	팔레트에서 워크스페이스로 드래그
노드 설정	노드 더블클릭 → 우측 패널에서 편집 → Done
노드 연결(와이어)	노드의 출력 점(우측) 을 드래그해서 다른 노드의 입력 점(좌측) 에 놓기
와이어 끊기	와이어를 클릭해서 선택 후 `Delete`
다중 선택	`Shift` 드래그로 영역 선택, 또는 `Ctrl/Cmd + 클릭` 으로 추가 선택
복사 / 붙여넣기	`Ctrl/Cmd + C` / `Ctrl/Cmd + V`
검색	`Ctrl/Cmd + F` — 팔레트에서 노드 이름 검색
흐름 가져오기	메뉴 → 가져오기 → JSON 붙여넣기 (이 문서의 예제 코드를 그대로 import 가능)

변경은 Deploy 가 되어야 살아있습니다

노드를 추가/삭제/수정해도 Deploy 를 누르기 전까지는 게이트웨이가 그 변경을 모릅니다. 빨간 점 (●) 이 표시된 노드는 “저장 안 된 변경 있음” 을 뜻합니다.

4. 메시지(`msg`) 의 기본 구조

노드 사이를 흐르는 데이터는 항상 msg 라는 자바스크립트 객체 입니다. 가장 자주 쓰는 필드:

필드	의미
`msg.payload`	본문(주된 데이터). 숫자/문자/객체/버퍼 모두 가능
`msg.topic`	토픽(분류 라벨). MQTT/Switch/Join 등에서 자주 사용
`msg.timestamp`	타임스탬프 (필요할 때 직접 채움)
`msg._msgid`	Node-RED 가 자동으로 부여하는 고유 ID — 추적용

대부분의 노드는 msg.payload 만 가지고 동작합니다.

5. 엣지 노드 — 한눈에 (게이트웨이 전용)

팔레트 좌측 엣지 카테고리에 게이트웨이가 자체 등록한 두 개의 노드가 있습니다. 거의 모든 IIoT 플로우의 입력/출력 입니다.

아이콘	노드	영문명	동작	호출하는 REST
⬇	태그값 읽기 (`pp-tag-read`)	`read tag value`	한 태그의 현재값 가져오기 (캐시 또는 PLC 직접 read)	`GET /api/v1/tag/{tagId}/value`
⬆	태그값 쓰기 (`pp-tag-write`)	`write tag value`	한 태그에 값 쓰기 (PLC 에 즉시 반영)	`POST /api/v1/tag/{tagId}/value`

inject (1s) ──▶ 태그값 읽기 ──▶ 처리 (function/switch/...) ──▶ 태그값 쓰기 / mqtt out / debug / file ...

노드를 찾는 법 — 팔레트 검색창에 read tag 또는 엣지 입력 → 두 노드만 필터링. 옅은 파스텔 블루 색상.

노드 설정에서 자주 비워두는 것	동적으로 채우는 방법
Tag ID	흐름 중 `msg.tagId = 'TAG_...'` 로 동적 지정 (한 노드를 여러 태그에 재사용)
Value (쓰기 노드)	`msg.value` 또는 `msg.payload` 로 흐름 중 채움

쓰기는 위험합니다 — 테스트 태그로 검증 먼저

실설비에 직접 쓰기 적용하기 전에 외부 시뮬레이터 또는 테스트 태그 로 충분히 검증하세요. write 권한은 운영팀과 합의된 태그에만.

자세한 필드 / 입출력 / 모든 프로토콜 지원 표 → 엣지 카테고리 (태그 읽기/쓰기)

6. 첫 번째 플로우 — Hello World

목표: 5초마다 한 태그를 읽어서 Debug 사이드바에 출력.

팔레트에서 inject 노드를 드래그 → 더블클릭 → Repeat: interval every 5 seconds → Done
엣지 → 태그값 읽기 노드 드래그 → Tag ID 에 실제 태그 (예: TAG_TEST_00042) 입력 → Done
팔레트 debug 노드 드래그
세 노드를 inject → 태그값 읽기 → debug 순서로 와이어 연결
우상단 Deploy 클릭
우측 사이드바의 debug 탭을 열어 5초마다 값이 찍히는지 확인

이 패턴(주기 트리거 → 읽기 → 처리) 이 모든 IIoT 플로우의 기본형 입니다.

7. 다음 단계

좌측 메뉴 순서대로:

기본 노드 사용법 — IIoT 에서 자주 쓰는 14개 노드의 기능
엣지 노드 (태그 읽기/쓰기) — 게이트웨이 전용 노드 (위 5절 한눈에 보기 의 자세한 버전)
MQTT 노드 자세히 — Broker 설정 / Pub / Sub / LWT / Birth
OPC-UA 노드 자세히 — Endpoint / Item / Client / Subscribe / Browse
Sparkplug B 노드 자세히 — Group / Edge / Birth-Death / 송수신
IIoT 예제 모음 — 현장에서 자주 만드는 12 가지 패턴
트러블슈팅 — 자주 빠지는 함정

8. 더 알아보기

OPC-UA 노드 뷰어 (/ui/opcua) 에서 현재 게이트웨이가 가지고 있는 모든 태그/값/노드ID 를 한눈에. → OPC-UA 노드 뷰어 사용하기
REST API 자체는 고급 / 통합 파트너용 → REST API 챕터. Node-RED 의 pp-tag-read / pp-tag-write 는 그 API 의 얇은 래퍼 입니다.
Node-RED 공식 매뉴얼: <https://nodered.org/docs/>

1. 접속​

2. 화면 구성​

3. 기본 조작 — 알아두면 편한 단축키​

4. 메시지(msg) 의 기본 구조​

5. 엣지 노드 — 한눈에 (게이트웨이 전용)​

6. 첫 번째 플로우 — Hello World​

7. 다음 단계​

8. 더 알아보기​