Toggle Button

Toggle button 위젯은 대시보드에 두 가지 상태(체크됨/체크 안 됨)의 제어 버튼을 추가합니다. HMI 장치를 켜짐/꺼짐, 열림/닫힘, 사용/사용 안 함 상태 사이에서 전환할 때 씁니다. 상태가 바뀔 때마다 HMI 장치 속성을 갱신하거나 시계열 기록을 쓸 수 있습니다.

주요 기능

HMI 장치나 엔티티를 위한 두 가지 상태(체크됨/체크 안 됨) 제어.
불러올 때 속성이나 텔레메트리 값에서 HMI 장치의 현재 상태를 읽습니다.
상태가 바뀔 때마다 속성 갱신이나 텔레메트리 쓰기를 따로 정합니다.
체크됨과 체크 안 됨 상태의 스타일을 따로 정합니다.
HMI 장치 데이터, 알람, 대시보드 상태에 따라 자동으로 비활성화할 수 있습니다.

위젯 추가

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

구성

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

데이터 소스

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

장치 — 특정 HMI 장치. 버튼이 이 HMI 장치의 속성과 텔레메트리 데이터를 읽어 상태를 정합니다.
개체 별명 — 엔티티 별칭에 맞는 엔티티 집합. 실행 중에 대상 HMI 장치를 동적으로 고를 때 씁니다.

동작

동작 영역은 토글이 초기 상태를 읽는 방법, 체크됨으로 바뀔 때와 체크 안 됨으로 바뀔 때 실행할 동작, 비활성화되는 시점을 정합니다. 필요한 하위 영역을 설정합니다. 비활성화 상태는 선택 사항입니다.

초기 상태

대시보드를 불러올 때 토글을 체크됨으로 보일지 체크 안 됨으로 보일지 정합니다. 아래 동작 유형 중 하나를 고릅니다.

아무 것도 하지 않음

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

매개변수 설명
Value 버튼을 항상 켜진 것으로 보이려면 체크됨, 항상 꺼진 것으로 보이려면 체크 안 됨으로 정합니다.

매개변수	설명
Value	버튼을 항상 켜진 것으로 보이려면 체크됨, 항상 꺼진 것으로 보이려면 체크 안 됨으로 정합니다.

속성 가져오기

HMI 장치나 엔티티의 속성을 읽어 현재 상태를 정합니다.

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

시계열 가져오기

최신 텔레메트리 값을 읽어 현재 상태를 정합니다.

매개변수	설명
시계열 키	감시할 텔레메트리 키(예: `state`, `power`).
조건(없음)	텔레메트리 값이 지정한 값과 같으면 체크됨입니다.
조건(함수)	`f(data)` 함수가 `true`를 돌려주면 체크됨입니다.

알람 상태 가져오기

엔티티에 조건에 맞는 알람이 활성이면 토글을 체크됨으로 정합니다.

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

현재 열린 대시보드 상태에 따라 토글을 정합니다. 버튼 상태가 탐색 맥락을 반영해야 할 때 씁니다.

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

대시보드 상태 컨텍스트 전체로 토글을 정합니다. 상태 매개변수 여러 개를 한꺼번에 확인해야 할 때 씁니다.

매개변수 설명
조건(함수만) f(data) 함수를 작성해 true를 돌려주면 토글이 체크됨이 됩니다.

매개변수	설명
알람 심각도	체크됨 상태를 일으킬 심각도: 심각한, 주요한, 작은, 경고, 중간.
알람 유형	모든 알람 또는 특정 알람 유형.

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

매개변수	설명
조건(함수만)	`f(data)` 함수를 작성해 `true`를 돌려주면 토글이 체크됨이 됩니다.

체크(켜짐 상태)

사용자가 버튼을 체크됨으로 바꿀 때 실행할 동작을 정합니다(예: HMI 장치 켜기, 문 열기, 공정 시작). 아래 동작 유형 중 하나를 고릅니다.

속성 설정

체크할 때 HMI 장치 속성을 갱신합니다.

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

체크할 때 시계열 기록을 씁니다.

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

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

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

체크 해제(꺼짐 상태)

사용자가 버튼을 체크 안 됨으로 바꿀 때 실행할 동작을 정합니다(예: HMI 장치 끄기, 문 닫기, 공정 중지). 체크의 반대로 설정합니다. 아래 동작 유형 중 하나를 고릅니다.

속성 설정

체크를 해제할 때 HMI 장치 속성을 갱신합니다.

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

체크를 해제할 때 시계열 기록을 씁니다.

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

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

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

비활성화 상태

비활성화 상태는 설정한 조건이 맞으면 버튼을 누를 수 없게 해, 위험하거나 올바르지 않은 상황에서 클릭을 막습니다.

아무 것도 하지 않음

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

매개변수 설명
Value 버튼을 항상 비활성화하려면 참, 항상 활성화해 두려면 거짓으로 정합니다.

매개변수	설명
Value	버튼을 항상 비활성화하려면 참, 항상 활성화해 두려면 거짓으로 정합니다.

속성 가져오기

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

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

시계열 가져오기

최신 텔레메트리 값(예: 운전 모드, 가용성 측정값)에 따라 버튼을 비활성화합니다.

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

알람 상태 가져오기

특정 알람이 활성인 동안 버튼을 비활성화합니다(예: Critical 알람이 열려 있는 동안 제어 막기).

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

현재 열린 대시보드 상태에 따라 버튼을 비활성화합니다. 읽기 전용이나 제한된 화면에서 동작을 막을 때 씁니다.

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

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

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

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

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

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

모양

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

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

버튼 모양

상태마다 버튼의 시각 스타일을 따로 정합니다. 이 영역에는 체크됨(켜짐 상태)과 체크 안 됨(꺼짐 상태) 탭 두 개가 있습니다.

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

카드 모양

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

액션

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

예시

문 열기/닫기 제어

시나리오: 스마트 슈퍼마켓에 문을 제어하는 Main Door라는 HMI 장치가 있습니다. HMI 장치는 공유 속성 doorState에서 상태를 읽고, 속성 갱신으로 문을 열거나 닫습니다.

사전 준비:

MX On Cloud에 Main Door라는 HMI 장치를 만들고 라이선스를 등록합니다(HMI 장치 연결 가이드 참고).
공유 속성을 추가합니다: 키 — doorState, 데이터 유형 — String, 값 — closed.
HMI 장치가 doorState 공유 속성 갱신을 구독하는지 확인합니다.

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

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

3단계. 동작 설정.

초기 상태: 속성 가져오기 — 범위: 공유, 키: doorState, 조건: 없음 — 결과가 opened(String)이면 체크됨.

체크(켜짐 상태): 속성 설정 — 범위: 공유, 키: doorState, Value: 상수 — opened(String).

체크 해제(꺼짐 상태): 속성 설정 — 범위: 공유, 키: doorState, Value: 상수 — closed(String).

4단계. 버튼 모양 설정.

체크됨 탭: 레이아웃 — 윤곽선, 라벨 — Opened, 색상 팔레트 기본 — 초록.

체크 안 됨 탭: 레이아웃 — 채움, 라벨 — Closed, 색상 팔레트 기본 — 빨강.

5단계. 카드 모양 설정. 카드 패딩을 0px로 정합니다.

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

결과: 위젯이 Main Door의 doorState를 읽습니다. doorState = "opened"이면 버튼에 Opened(흰 배경, 초록 라벨)가, doorState = "closed"이면 Closed(빨간 채우기)가 표시됩니다. 버튼을 전환하면 새 값을 doorState에 쓰고, HMI 장치는 갱신을 받아 실제 상태를 바꿉니다.

문제 해결

토글에 예상한 상태가 반영되지 않음

원인	해결 방법
속성 키가 틀림	키가 HMI 장치 속성과 정확히 같은지 확인합니다. 키 이름은 대소문자를 구분합니다.
속성 범위가 틀림	범위를 실제 속성 유형(클라이언트 / 서버 / 공유)에 맞춥니다.
HMI 장치에 속성이 없음	장치 → 속성을 열고 키가 값과 함께 있는지 확인합니다.
결과 변환기가 늘 같은 값을 돌려줌	함수 변환기를 검토합니다. `return` 문이 빠졌거나 비교가 틀리지 않았는지 확인합니다.

클릭해도 토글 상태가 바뀌지 않음

원인	해결 방법
체크나 체크 해제 동작이 잘못 설정됨	동작 유형과 매개변수가 HMI 장치가 기대하는 인터페이스(속성 키 등)와 맞는지 확인합니다.
속성 범위가 맞지 않음	속성 설정 동작의 범위는 서버나 공유여야 합니다. 클라이언트 속성은 대시보드에서 쓸 수 없습니다.
값 유형이 틀림	상수 값의 유형(String, Boolean, Integer)이 HMI 장치가 기대하는 유형과 맞는지 확인합니다.