Command Button

Command button 위젯은 대시보드에 한 번 클릭으로 실행하는 동작 컨트롤을 추가합니다. 버튼을 한 번 눌러 HMI 장치 속성을 갱신하거나 텔레메트리 기록을 쓸 때 씁니다. Toggle button이나 Power button과 달리 Command button에는 지속되는 상태가 없습니다. 동작을 실행한 뒤 대기 모양으로 돌아갑니다.

주요 기능

HMI 장치나 엔티티에 한 번 클릭으로 실행하고 끝나는 동작.
클릭 시 동작 유형: 속성 설정, 시계열 추가.
속성, 텔레메트리, 알람, 대시보드 상태에 따른 비활성화 상태(선택 사항).
호버, 눌림, 활성(동작 직후 깜박임), 비활성화 상호작용 상태의 시각 피드백.
라벨, 아이콘, 레이아웃, 색상 팔레트를 설정할 수 있습니다.

위젯 추가

대시보드를 수정 모드로 엽니다. 위쪽 툴바의 위젯 추가를 클릭하거나, 빈 대시보드 가운데의 위젯 추가 아이콘을 클릭합니다.
위젯 번들 선택 대화상자에서 Buttons를 찾아 클릭합니다.
Command button 위젯을 선택합니다.
데이터 소스, 동작, 모양을 설정한 다음 추가를 클릭합니다.

구성

이 절의 설정은 모두 기본 모드 기준입니다. 필수 항목만 다루는 빠른 설정입니다. 카드 스타일, 카드 버튼, 제목, 툴팁 같은 세부 설정은 고급 탭으로 바꿉니다.

데이터 소스

위젯의 데이터 소스를 선택합니다.

장치 — 특정 HMI 장치. 위젯이 클릭 시 이 HMI 장치에 동작을 보내고, 비활성화 조건을 위해 데이터를 읽습니다.
개체 별명 — 엔티티 별칭에 맞는 엔티티 집합. 실행 중에 대상 HMI 장치를 동적으로 고를 때 씁니다.

동작

동작 영역은 버튼을 클릭했을 때 실행할 동작과 버튼이 비활성화되는 시점을 정합니다. 비활성화 상태는 선택 사항입니다.

클릭 시

사용자가 버튼을 누르면 실행할 동작을 정합니다. 아래 동작 유형 중 하나를 고릅니다.

속성 설정

버튼을 누르면 HMI 장치 속성을 갱신합니다.

매개변수 설명
속성 범위 서버 또는 공유.
속성 키 갱신할 속성(예: command, state).
Value 상수 — 고정 값(예: "triggered", true), 함수 — 값을 돌려주는 JS 함수.
시계열 추가

버튼을 누르면 시계열 기록을 씁니다. 동작을 기록할 때 유용합니다.

매개변수 설명
시계열 키 쓸 텔레메트리 키(예: commandLog, lastAction).
Value 상수 — 고정 값, 함수 — 값을 돌려주는 JS 함수.

매개변수	설명
속성 범위	서버 또는 공유.
속성 키	갱신할 속성(예: `command`, `state`).
Value	상수 — 고정 값(예: `"triggered"`, `true`), 함수 — 값을 돌려주는 JS 함수.

매개변수	설명
시계열 키	쓸 텔레메트리 키(예: `commandLog`, `lastAction`).
Value	상수 — 고정 값, 함수 — 값을 돌려주는 JS 함수.

비활성화 상태

비활성화 상태는 설정한 조건이 맞으면 버튼을 누를 수 없게 합니다. 이 상태에서는 버튼이 회색이 되고 클릭이 무시됩니다. 이 영역은 선택 사항입니다. 버튼을 항상 클릭할 수 있어야 하면 건너뜁니다.

아무 것도 하지 않음

비활성화 상태를 직접 정합니다. 실시간 데이터가 필요 없습니다.

매개변수 설명
Value 켜짐 — 버튼이 항상 비활성화됩니다. 꺼짐 — 버튼이 항상 활성화됩니다.

매개변수	설명
Value	켜짐 — 버튼이 항상 비활성화됩니다. 꺼짐 — 버튼이 항상 활성화됩니다.

속성 가져오기

HMI 장치 속성(예: active 플래그, locked 상태)에 따라 버튼을 비활성화합니다.

매개변수	설명
속성 범위	속성이 저장된 곳: 전체, 클라이언트, 서버, 공유.
속성 키	읽을 속성 이름(예: `active`, `enabled`).
조건(없음)	속성이 지정한 값(String, Integer, Double, Boolean, JSON)과 같으면 비활성화합니다.
조건(함수)	`f(data)` 함수가 `true`를 돌려주면 비활성화합니다.

시계열 가져오기

최신 텔레메트리 값에 따라 버튼을 비활성화합니다.

매개변수	설명
시계열 키	감시할 텔레메트리 키(예: `availability`, `status`).
조건(없음)	텔레메트리 값이 지정한 값과 같으면 비활성화합니다.
조건(함수)	`f(data)` 함수가 `true`를 돌려주면 비활성화합니다.

알람 상태 가져오기

특정 알람이 활성인 동안 버튼을 비활성화합니다(예: 심각한 고장 중 제어 막기).

매개변수 설명
알람 심각도 심각한, 주요한, 작은, 경고, 중간.
알람 유형 모든 알람 또는 특정 알람 유형.
대시보드 상태 ID 가져오기

현재 열린 대시보드 상태에 따라 버튼을 비활성화합니다.

매개변수 설명
조건(없음) 현재 상태 이름이 입력한 글자와 같으면 비활성화합니다.
조건(함수) f(data) 함수가 true를 돌려주면 비활성화합니다.
대시보드 상태 객체 가져오기

대시보드 상태 컨텍스트 전체로 버튼을 비활성화합니다. 상태 매개변수 여러 개를 한꺼번에 평가해야 할 때 씁니다.

매개변수 설명
조건(함수만) f(data) 함수를 작성해 true를 돌려주면 버튼이 비활성화됩니다.

매개변수	설명
알람 심각도	심각한, 주요한, 작은, 경고, 중간.
알람 유형	모든 알람 또는 특정 알람 유형.

매개변수	설명
조건(없음)	현재 상태 이름이 입력한 글자와 같으면 비활성화합니다.
조건(함수)	`f(data)` 함수가 `true`를 돌려주면 비활성화합니다.

매개변수	설명
조건(함수만)	`f(data)` 함수를 작성해 `true`를 돌려주면 버튼이 비활성화됩니다.

모양

위젯 헤더와 제목 영역을 설정합니다.

설정	설명
자동 크기 조절	위젯 크기를 바꾸면 글꼴 크기와 요소 비율을 자동으로 조정합니다.
제목	위젯 헤더에 표시되는 글. 엔티티 변수 `$\{entityName\}`, `$\{entityLabel\}`을 지원합니다.
카드 아이콘	제목 옆에 표시되는 Material Design 아이콘. 크기(px)를 설정할 수 있습니다.

버튼 모양

버튼의 시각 스타일을 설정합니다.

설정	설명
레이아웃	버튼 시각 스타일: 윤곽선(테두리), 채움(단색 채우기), 밑줄(밑줄만), 기본(일반 글자).
라벨	버튼에 표시되는 글(예: `Restart`, `Reboot HMI Device`, `Trigger relay`). 엔티티 변수 `$\{entityName\}`, `$\{entityLabel\}`을 지원합니다.
아이콘	버튼에 표시되는 Material Design 아이콘. 크기(px)를 설정할 수 있습니다.
테두리 반경	버튼 모서리의 둥근 정도(px).
색상 팔레트	기본: 버튼 채우기나 글자 색상, 배경: 주변 영역 색상.
사용자 지정 스타일	상호작용별 스타일 재정의: 활성화(기본), 호버, 눌림, 활성(동작이 성공한 직후 잠깐 보이는 스타일), 비활성화. 상태마다 기본, 배경, 그림자 설정이 있습니다.

카드 모양

설정	설명
배경	카드 배경으로 쓰는 단색이나 이미지.
카드 버튼 표시	카드 헤더의 전체화면 버튼 표시 여부를 켜고 끕니다.
카드 모서리 반경	카드 모서리의 둥근 정도.
카드 패딩	카드 내용과 테두리 사이 간격.

액션

Command button 위젯은 위젯 헤더 버튼 동작을 지원합니다. 위젯 헤더에 버튼을 추가해 클릭하면 설정한 동작을 실행합니다.

예시

환기 재시작 버튼

시나리오: 스마트 환기 시스템에 Ventilation Relay라는 HMI 장치가 있습니다. 환기 과정을 다시 시작하는 Restart Ventilation 버튼을 대시보드에 추가합니다. HMI 장치가 명령을 받을 준비가 되지 않았다고 보고하면 버튼이 자동으로 비활성화됩니다.

사전 준비:

MX On Cloud에 Ventilation Relay라는 HMI 장치를 만들고 라이선스를 등록합니다(HMI 장치 연결 가이드 참고).
공유 속성을 추가합니다: 키 — active, 데이터 유형 — Boolean, 값 — true.

1단계. 위젯 추가. 대시보드를 수정 모드로 열고 위젯 추가를 클릭하고 Buttons 번들을 선택한 다음 Command button을 고릅니다.

2단계. 데이터 소스 설정. 대상 장치를 Ventilation Relay로 정합니다.

3단계. 동작 설정.

클릭 시: 속성 설정 — 메서드: restartVentilation, 파라미터: 상수 — true(Boolean).

비활성화 상태: 속성 가져오기 — 범위: 공유, 키: active, 조건: 없음 — 결과가 false(Boolean)이면 비활성화.

4단계. 버튼 모양 설정. 레이아웃 — 윤곽선, 라벨 — Restart Ventilation, 아이콘 — restart_alt, 색상 팔레트 기본 — #2196F3, 배경 — #D0EBFF70.

5단계. 저장. 추가를 클릭하고 필요하면 크기와 위치를 조정한 다음 대시보드 툴바의 저장을 클릭합니다.

결과: active = true이면 버튼이 파랗고 클릭할 수 있습니다. 누르면 HMI 장치에 {"method": "restartVentilation", "params": true}를 보냅니다. HMI 장치가 오프라인이면 명령이 대기열에 들어갔다가 다시 연결되면 전달됩니다. active = false이면 버튼이 회색이 되고 클릭이 무시됩니다.

문제 해결

버튼을 클릭해도 반응이 없음

원인	해결 방법
속성 키나 범위가 틀림	속성 설정 동작이면 키와 범위(서버 또는 공유)가 HMI 장치 속성과 맞는지 확인합니다.
값 유형이 틀림	상수 값의 유형(String, Boolean, Integer)이 HMI 장치나 속성이 기대하는 유형과 맞는지 확인합니다.

버튼이 항상 비활성화됨

원인	해결 방법
속성 키를 찾을 수 없음	장치 → 속성을 열고 키가 값과 함께 있는지 확인합니다.
속성 범위가 틀림	범위를 실제 속성 유형(클라이언트 / 서버 / 공유)에 맞춥니다.
조건 값이 반대로 설정됨	조건 값이 버튼을 비활성화할 값과 맞는지 확인합니다. 버튼을 비활성화해야 할 때 속성이 `false`라면 조건 값을 `false`로 정합니다.
함수 변환기가 항상 `true`를 돌려줌	함수 변환기를 검토합니다. `return` 문이 빠졌거나 비교가 틀리지 않았는지 확인합니다.