설비 명령 (커맨드 레지스트리)

플랜트펄스는 태그에 값을 쓰는 일(제어쓰기) 위에 「이 설비에서 무엇을 할 수 있는가」 라는 한 겹을 더 둡니다. 이것이 커맨드 레지스트리입니다.

운영자는 TAG_CNC01_SPEED_SP 에 1200 을 쓰지 않고 「속도 설정 (SET_SPEED)」 을 고르고 속도만 입력합니다. 어떤 태그에 어떤 순서로 쓸지, 무엇이 참일 때만 허용할지는 관리자가 미리 정의해 둡니다.

이 화면은 실제로 설비를 움직인다

여기서 [실행] 을 누르면 PLC 에 값이 실제로 써집니다. 시험은 반드시 시뮬레이터 연결이나 정지된 설비에서 하세요. 자동 롤백은 없습니다 — 시퀀스 중간에 실패해도 그 앞에서 이미 쓴 값은 되돌아가지 않습니다(감사 기록을 보존하기 위한 설계입니다).

어디에 있나

에셋 화면(/asset/tree/index)에서 설비(EQUIPMENT) 노드를 고르면 하단에 탭이 열립니다.

탭	하는 일
명령	정의된 커맨드를 고르고 실행한다 · 최근 명령 이력
레지스트리	커맨드를 정의한다(등록·편집·삭제) · 에셋 스테이트먼트

「레지스트리」 탭을 찾으세요

정의는 레지스트리 탭 안의 «명령 레지스트리» 패널에 있습니다. 탭 이름이 «명령» 이 아니라 «레지스트리» 라 처음에는 엉뚱한 탭을 뒤지기 쉽습니다.

볼 수 있는 사람 · 실행할 수 있는 사람

접근이 세 겹으로 걸려 있습니다.

겹	어디서	거르는 것
① URL 필터	`security-rule.xml` 의 `/asset//command`	ADMIN · MANAGER 외에는 URL 자체가 막힙니다
② 화면·컨트롤러	명령 탭의 커맨드 실행 패널	ADMIN / MANAGER 에게만 보입니다. 그 외 역할은 하단 이력만 봅니다. 서버도 미인증 401 · 비 ADMIN/MANAGER 403
③ 커맨드별	정의의 허용 역할	커맨드 하나하나에 «누가 실행할 수 있는가» 를 따로 지정합니다. 불허 시 `REJECTED_FORBIDDEN`

②까지 통과해도 ③에서 막힐 수 있습니다 — 커맨드 단위로 더 좁힐 수 있다는 뜻입니다.

실제로는 ADMIN 만입니다

접근 제어는 «ADMIN 또는 MANAGER» 라고 적혀 있지만, MANAGER 는 사용자 등록 화면에서 부여할 수 없는 역할입니다(선택지가 ADMIN·API·USER 셋뿐). API 로 억지로 넣으면 그 계정은 로그인 후 진입하지 못합니다 — 사용자 관리 참고.

그러니 이 화면을 쓸 수 있는 사람은 사실상 ADMIN 뿐입니다. 정의의 «허용 역할» 도 ADMIN 과 API 만 실효가 있습니다.

커맨드를 정의한다 — 레지스트리 탭

[명령 등록] 을 누르면 정의 다이얼로그가 열립니다. 화면 안내 그대로 «이 자산의 의미 커맨드를 정의합니다. 파라미터·사전조건과 순서대로 실행되는 태그 쓰기 스텝을 구성하세요.»

기본 정보

항목	필수	설명
커맨드 타입	✅	의미 구분자 — `START` · `STOP` · `SET_SPEED` 같은 값
커맨드 이름	✅	실행 셀렉트 박스에 보이는 이름
허용 역할		ADMIN · MANAGER · API 체크박스. «이 커맨드를 실행할 수 있는 역할»
순서		목록 정렬 순서 (작을수록 먼저)
활성화		끄면 실행 셀렉트 박스에 나타나지 않습니다. 정의는 남습니다

허용 역할을 비워 두면 아무도 못 쓴다

권한 게이트는 fail-closed 입니다 — 요청자의 역할이 허용 역할 목록에 없으면 거절합니다. 비워 두면 목록이 빈 것이므로 ADMIN 이라도 REJECTED_FORBIDDEN 을 받습니다.

파라미터

실행할 때 운영자가 입력할 값을 표로 정의합니다. 행마다 이름 · 타입 · 최소 · 최대 · 옵션 · 필수 입니다.

타입	검사
Number	수치로 파싱되고 유한값이어야 합니다(`NaN`·`Infinity` 는 범위와 무관하게 거절). `최소`/`최대` 가 있으면 그 사이(경계 포함)
Boolean	`true` / `false` (대소문자 무시)
Enum	`옵션` 에 적어 둔 값 중 하나
String	검사 없음

필수 인데 비었으면 거절합니다(REJECTED_PARAM).
선택 파라미터는 비우면 타입 검사를 건너뛰고, 값이 들어오면 검사합니다.
파라미터가 아예 없는 커맨드도 됩니다.

커맨드 플로우 — 스텝 시퀀스

정의 다이얼로그의 커맨드 플로우 영역은 시각 편집기입니다. 왼쪽 팔레트에서 노드를 놓고(«클릭=끝에 추가 · 드래그=사이 삽입»), 오른쪽 인스펙터에서 그 노드의 값을 채웁니다.

[시작] → [쓰기] → [지연] → [읽기 확인] → [종료]

노드	인스펙터 항목	하는 일
쓰기 (`write`)	태그 · 값 표현식 · 사전조건(인터록)	그 태그에 값을 씁니다
읽기 확인 (`read_back`)	태그 · 연산자 · 기대값 · 안정화 시간 · 폴링 간격 · 허용오차	쓴 값이 실제로 반영됐는지 되읽어 확인합니다
지연 (`delay`)	지연 (ms)	다음 스텝까지 기다립니다

값 표현식 은 리터럴이거나 파라미터 참조입니다 — 화면 도움말 그대로 «리터럴 값 또는 표현식. {param} 은 같은 이름의 커맨드 파라미터로 치환됩니다.» {speed} · 1 · SET {speed} RPM 이 모두 됩니다.

읽기 확인 의 빈 칸은 기본값을 씁니다 — 안정화 2000 ms · 폴링 200 ms · 허용오차 0.0. PLC 값이 정착하는 데 시간이 걸리므로, 쓰자마자 되읽어 어긋나는 것을 이 정착창이 흡수합니다.

쓰기 스텝에 고를 수 있는 태그는 제한된다

쓰기 노드의 태그 목록에는 그 설비에 소속된 태그 중 rw 가 W 또는 RW 이고 tag_type 이 SETPOINT 또는 COMMAND 인 것만 나옵니다. 읽기 확인·사전조건의 태그 목록은 제한이 없습니다(읽기라서).

바꾸고 싶은 태그가 목록에 없다면 태그 속성 탭 에서 읽기/쓰기 와 태그 유형을 먼저 고치세요.

사전조건과 인터록

각 조건은 태그 · 연산자 · 값 세 칸이고, 인터록 체크박스가 하나 더 있습니다. 연산자는 eq · ne · gt · gte · lt · lte 입니다.

	인터록 아님	인터록
실행 시작 전	검사 ✅	검사 ✅
각 쓰기 스텝 직전	검사 안 함	다시 검사 ✅

안전 조건은 «인터록» 으로 걸어라

시퀀스에 지연이나 읽기 확인이 끼면 시작 시점과 실제 쓰기 시점 사이에 시간이 벌어집니다. 그 사이에 안전문이 열렸다면? 인터록을 걸어 둔 조건만 쓰기 직전에 다시 확인하고, 어긋나면 그 쓰기를 발행하지 않고 중단합니다.

「도어 닫힘 = TRUE」「비상정지 = FALSE」 같은 조건은 반드시 인터록으로 거세요.

조건 정의가 불량이어도 통과시키지 않습니다. 태그나 연산자가 빠졌거나 파싱이 안 되면 조용히 건너뛰지 않고 REJECTED_PRECONDITION 으로 막습니다 — 안전 게이트를 무력화하지 않기 위한 fail-closed 설계입니다.

커맨드를 실행한다 — 명령 탭

명령 탭의 커맨드 셀렉트 박스에서 고릅니다 — 활성 인 정의만, 순서대로 나옵니다. («활성화된 커맨드가 없습니다» 가 보이면 레지스트리에서 활성화하세요.)
[실행] — 파라미터가 정의돼 있으면 파라미터 입력 다이얼로그가 먼저 뜹니다 (타입에 맞는 컨트롤이 자동 생성됩니다 — Number 는 min/max, Enum 은 셀렉트, Boolean 은 참/거짓).
확인 다이얼로그 — 「자산 ○○ 에 커맨드 ○○ 을(를) 실행하시겠습니까?」 와 파라미터 요약. 오발 방지용이므로 여기서 대상 자산 이름을 꼭 읽으세요.
결과가 패널에 표시됩니다 — 스텝별로 태그 · 연산 · 요청 값 · 실측 값 · 성공 · 오류.

실행 순서 (고정)

정의 로드 → 에셋 확인 → 자산락 → 권한 → 파라미터 → 태그 스코프 → 사전조건
                                                                    ↓
                      종결 판정 ← 스텝 시퀀스(쓰기 직전 인터록 재검증) ←

자산락 은 같은 설비에 대한 커맨드를 완전히 순차로 만듭니다. 서로 다른 설비의 커맨드는 동시에 나갑니다.

결과 상태와 대처

상태	뜻	볼 곳
`SUCCESS`	모든 스텝 성공	—
`FAILED`	어느 스텝에서 실패해 거기서 멈췄다	결과 표의 «오류» 칸. 앞선 쓰기는 이미 반영돼 있다
`REJECTED_NOT_FOUND`	정의가 없거나 · 다른 설비의 정의거나 · 비활성	레지스트리에서 활성화 여부 확인
`REJECTED_FORBIDDEN`	내 역할이 그 커맨드의 허용 역할에 없다	정의의 허용 역할
`REJECTED_PARAM`	파라미터가 스펙에 안 맞는다	필수 누락 · 범위 · Enum 값
`REJECTED_TAG_SCOPE`	스텝이 가리키는 태그가 그 설비 소속이 아니거나 쓰기 불가가 됐다	정의를 만든 뒤 태그를 재배선하거나 `rw` 를 바꾼 경우
`REJECTED_PRECONDITION`	사전조건 불충족 — 또는 사전조건 정의 자체가 불량	조건 태그의 현재 값
`REJECTED_BUSY`	같은 설비에 다른 커맨드가 실행 중 (HTTP 409)	잠시 뒤 다시 누르세요

FAILED 는 «아무 일도 안 일어났다» 가 아니다

REJECTED_* 는 쓰기가 시작되기 전에 막힌 것이라 설비 상태가 바뀌지 않았습니다. 반면 FAILED 는 시퀀스에 들어간 뒤 멈춘 것이라, 실패한 스텝 앞의 쓰기는 이미 반영돼 있습니다. 결과 표에서 어디까지 성공했는지 확인하고 필요하면 손으로 되돌리세요.

REJECTED_BUSY 와 REJECTED_NOT_FOUND 만은 이력에 발행되지 않습니다(전송 전 경합·라우팅 오류).

시퀀스 상한

것	상한
시퀀스 전체	30,000 ms — 넘으면 그 스텝을 실행하지 않고 `FAILED`(op `deadline`)
읽기 확인	안정화 시간(기본 2,000 ms)
쓰기	엣지 HTTP 타임아웃

쓰기는 자동으로 재시도하지 않는다

읽기 확인은 폴링으로 여러 번 읽지만, 쓰기는 한 번만 나갑니다. 재발행은 부분 적용 위험이 있어 의도적으로 막아 두었습니다 — 실패하면 사람이 판단해 다시 실행하세요.

이력은 어디에 남나

종결된 실행은 표준 asset_command 로 발행돼 이력 테이블(tm_asset_command) · UNS · 타임라인 · 캐시에 함께 들어갑니다. 실패·거절은 진단 로그에도 남습니다 (진단).

명령 탭 하단의 «최근 명령 목록» 은 스테이트먼트가 발행한 명령까지 함께 보여 줍니다 — 타임스탬프 · 스테이트먼트명 · 키 · 값(JSON).

자주 묻는 질문

Q. 커맨드 실행 패널이 안 보입니다. A. 역할이 ADMIN(또는 부여 불가능한 MANAGER)이 아닙니다. USER·API 에는 하단 이력만 보입니다.

Q. 셀렉트 박스에 「활성화된 커맨드가 없습니다」 가 뜹니다. A. 정의가 없거나 전부 비활성입니다. 레지스트리 탭에서 활성화하세요.

Q. 쓰기 스텝의 태그 목록이 비어 있습니다. A. 그 설비에 rw 가 W/RW 이고 tag_type 이 SETPOINT/COMMAND 인 태그가 없습니다. 태그 속성 탭 에서 고치세요.

Q. 계속 REJECTED_BUSY 가 납니다. A. 같은 설비의 다른 커맨드가 아직 끝나지 않았습니다. 긴 지연이나 읽기 확인이 들어간 커맨드가 돌고 있는지 최근 명령 목록에서 확인하세요.

Q. 실행했는데 값이 안 바뀐 것 같습니다. A. 결과 표의 실측 값 칸을 보세요. 읽기 확인 스텝이 있다면 그 칸이 실제로 되읽은 값입니다. 읽기 확인 스텝이 없다면 쓰기가 나갔는지만 알 뿐 반영 여부는 모릅니다 — 중요한 커맨드에는 읽기 확인을 넣으세요.

어디에 있나​

볼 수 있는 사람 · 실행할 수 있는 사람​

커맨드를 정의한다 — 레지스트리 탭​

기본 정보​

파라미터​

커맨드 플로우 — 스텝 시퀀스​

사전조건과 인터록​

커맨드를 실행한다 — 명령 탭​

실행 순서 (고정)​

결과 상태와 대처​

시퀀스 상한​

이력은 어디에 남나​

자주 묻는 질문​

관련 화면​