사용자 도구

사이트 도구

English

comfilehmi:webapi:index

Web API (CHC 시리즈/HDM-C070RL & 펌웨어 v3.49 이상 지원)

Web API 기능은 HTTP 프로토콜을 사용하여 원격으로 HMI(서버 역할)와 통신하면서 여러가지 처리를 할 수 있는 기능입니다. (HMI 제어하기, HMI 변수나 메모리 값 등을 읽어오기, HMI에 있는 파일을 웹브라우저로 다운로드, 실행하기, 웹브라우저에 실시간 동작 UI 구성하기 등)

기존의 웹브라우저(예: 크롬)를 사용할 수도 있고 다른 HMI가 클라이언트가 되어 사용할 수도 있습니다('액션>HTTP 요청')

1. URL 작성하는 방법

HMI의 'HTTP 요청' 액션이나 웹브라우저 주소창에서 URL을 입력할 경우 다음과 같은 형식으로 해야 원격지 HMI(서버)가 인식할 수 있습니다.

IP주소 : 포트번호 / 커맨드명 / 원격제어 비밀번호 / 커맨드 내용

예1) 192.168.0.30:9138/script/1234/a=a+1;vars_to_json(“a”)
예2) 192.168.0.30/download//storage card/logs/log1.txt

서버가 ComfileHMI가 아닌 경우는 위와 같은 형식이 아닌 일반적인 자유로운 HTTP URL 형식으로 'HTTP 요청' 액션에서 전송 가능합니다.

1) IP 주소

IP주소는 내부 네트워크 주소(예: 192.168.0.20) 또는 도메인(예: myserver.com)을 쓸 수 있습니다.

2) 포트번호

포트번호는 서버 쪽에서 설정한 포트 번호를 쓰면 되고, 생략 가능합니다.(생략시 80으로 간주)

3) 커맨드명

커맨드는 어떤 동작을 수행할지 결정하는 것이고 다음과 같은 종류가 있습니다.

(1) 'script'

HMI의 [액션>스크립트]에서 사용하는 스크립트를 사용합니다. HMI 변수, 문자열 변수, 함수 등을 사용할 수 있으며 세미콜론(';')으로 연결하여 스크립트를 길게 작성할 수 있습니다.

(2) 'open'

HMI 액션에서는 지원하지 않고 웹브라우저에서만 지원되는 커맨드입니다.
HTML이나 이미지 파일, mp3, wav 파일 등 웹브라우저에서 인식 가능한 포맷을 웹브라우저로 불러 들여 표시/재생할 수 있습니다.

(3) 'download'

HMI 액션에서는 지원하지 않고 웹브라우저에서만 지원되는 커맨드입니다.
파일 종류를 가리지 않고 어떤 파일이든 웹브라우저를 통해 파일 자체를 그대로 다운로드 받을 수 있습니다.

4) 원격제어 비밀번호

서버의 '런타임 설정>서버>비밀번호 설정'에서 설정된 비밀번호를 입력합니다. 서버 측에 비밀번호가 설정되지 않았다면 이 값은 생략할 수 있습니다.

5) 커맨드 내용

(1) 'script'의 경우

스크립트 내용을 입력합니다. 특별히, 서버 측에서 가져오고 싶은 변수값이나 메모리 내용등이 있다면 vars_to_json , mem_to_json 함수를 함께 사용합니다. (자세한 내용은 함수 설명 참조) 예) a=a+1;vars_to_json(“a”)
HMI 액션과 웹브라우저에서 모두 사용할 수 있습니다.

(2) 'open'이나 'download'의 경우

웹브라우저 전용 커맨드의 커맨드 내용으로서 서버 HMI 상의 파일 경로를 지정해줍니다.
파일 경로는 SD카드에 있는 파일만 지정할 수 있으며 storage card/로 시작합니다. 폴더 구분자로 '\'가 아닌 '/'을 사용합니다.

예1) 192.168.0.30:9138/open//storage card/MyWebHmi/index.htm
예2) 192.168.0.30:9138/download//storage card/logs.txt

6) 웹브라우저 주소창에서 사용시 제약 사항

웹브라우저 주소창에서는 '#' , '%' , '\' 문자들을 직접적으로 표현하지 못하므로 다음과 같이 치환하여 사용합니다.

'#' → '%23'
'%' → '%25'
'\' → '%5C' (파일 경로일 경우 간단하게 '/'로도 치환 가능)

예1) 192.168.0.20:9138/script//$a=“3 나누기 5는 백분율로 60%25입니다.”;vars_to_json(“$a”)
예2) 192.168.0.20:9138/open//storage card/web_hmi.html
예3) 192.168.0.20:9138/download//storage card/sub/data.bin
예4) 192.168.0.20:9138/script/filenames_to_json(“storage card/dir”)

2. 응답 처리하는 방법

ComfileHMI는 적절한 포맷을 갖춘 'script' 커맨드 요청이 왔을 때 혹은 URL에 오류가 있을 경우 'JSON' 형식으로 응답합니다.
웹브라우저 전용 'open'이나 'download' 커맨드의 경우는 실패한 경우에만 JSON 형식으로 응답합니다.

1) HMI 클라이언트에서 응답 처리하는 방법

HMI 클라이언트는 들어오는 JSON 응답을 자체적으로 해석할 수 있는 능력이 있으므로 별도로 JSON에 관한 처리를 안하더라도 자동으로 처리됩니다. 원격지 HMI 변수값이나 HMI 메모리값이 JSON 형식으로 수신되면 HMI 클라이언트는 그 내용을 그대로 자신에게 복사합니다.(같은 변수명, 같은 메모리 번지로)
도착한 JSON 응답이 자동 처리된 후 실행할 사용자 액션을 지정할 수 있습니다.
JSON 응답에는 변수값이나 메모리값 등의 정보 이외에도 성공했는지 여부, 에러일 경우 에러코드와 에러메시지 정보도 담길 수 있습니다. 가장 최근에 응답 온 JSON 관련해서, 성공여부는 last_json_result() 함수, 에러 코드는 last_json_error_code() 함수, 에러메시지는 last_json_error_message() 함수를 사용하여 알아낼 수 있습니다. 이 함수들에 대한 자세한 설명은 다음 링크를 참고하세요 : WebAPI 관련 함수

2) 웹브라우저에서 응답 처리하는 방법 (HTML / javascript / JSON에 대한 이해 필요)

download나 open 커맨드의 경우 성공할 경우 웹브라우저에 결과 동작이 반영되므로 JSON을 처리하는 문제를 고려할 필요가 없지만, script 커맨드의 경우는 응답이 항상 JSON 형식으로 도착하므로 들어오는 JSON 응답을 처리하려면 해당 처리를 할 수 있는 HTML 소스 코드를 직접 작성해두어야 합니다. 작성된 HTML 소스는 SD카드의 적당한 위치에 위치시키고 open 커맨드를 통해 웹브라우저로 불러옵니다.(HTML 파일은 반드시 원격지 HMI 에 있어야 하며 웹브라우저가 존재하는 로컬 PC에 존재하면 제대로 실행이 안될 수 있음)

쉬운 예제) 변수 a 값과 HMI 메모리의 5,6 번지의 값을 원격지에 있는 HMI로부터 받아서 실시간으로 (200ms 주기로) 웹브라우저에 표시합니다.
쉬운 예제 HTML 파일 다운로드 받기

고급 예제) 웹브라우저의 슬라이더로 원격지 HMI에 있는 변수 a의 값을 쓰고, 다시 그 값을 불러 와서 웹브라우저의 게이지 그래프에 표시하는 예제. 슬라이더의 값이 정한 범위(0~100)를 넘어가면 게이지가 빨간색으로 변합니다.
고급 예제 HTML 파일 다운로드 받기

<예제 테스트 절차>
1. 다운로드 받은 sample1.htm 또는 sample2.htm 파일을 HMI의 storage card 폴더 밑에 복사한다.(SD카드의 루트 폴더)
복사하기 전에, htm 소스 코드 내부에 원격 IP 주소 설정하는 부분 중 '서버 주소:포트 번호'를 환경에 맞게 변경해줘야 한다.('192.168.0.99:9138'이라고 되어 있는 부분)
2. HMI의 런타임 [설정>서버>원격 제어 서버 구동]에 체크하고 네트워크탭을 해당 환경에 맞게 설정해준다.
3. 웹브라우저를 실행하고 주소창에 URL을 입력한다.
예) 192.168.0.99:9138/open//storage card/sample1.htm (서버 주소가 192.168.0.99이고 포트번호가 기본 포트 번호인 9138이고 설정된 비밀번호가 없는 경우)

3. JSON 응답 형식

필드명 타입 내용
success boolean 성공 여부. true이면 성공. false이면 실패
vars.{HMI 변수명} number vars_to_json() 함수로 요청한 원격지 HMI 숫자 변수의 값.
vars.{HMI 문자열 변수명} string vars_to_json() 함수로 요청한 원격지 HMI 문자열 변수의 값.
문자열 변수명은 '$'로 시작함.
mem.{HMI 메모리 시작 번지} array mem_to_json() 함수로 요청한 원격지 HMI 메모리의 주소 연속적인 값들
error.code number 오류 코드
error.message string 오류 메세지. 언어는 프로젝트 기본 언어 설정에 따라
filenames array filenames_to_json() 함수로 요청한 원격지 HMI 특정 폴더 내의 파일명 목록
dirnames array dirnames_to_json() 함수로 요청한 원격지 HMI 특정 폴더 내의 폴더명 목록
예1) 성공했을 경우
{
	"success": true,
	"vars": {
		"temperature" : 16.7,
		"$city" : "Seoul"
	},
	"mem" : {
		"20" : [31,43,21]
	}
}

예2) 실패했을 경우
{
	"success" : false,
	"error" : {
		"code" : 4011,
		"message" : "Command syntax error."
	}
}

Web API 에러 코드와 에러 메세지

오류 코드 오류 메세지
8047 응답받은 JSON의 형식이 잘못되었습니다.
4011 커맨드의 구문 오류입니다. 다음과 같이 사용하세요 : 서버 주소:포트번호/커맨드명/비밀번호/커맨드 내용
4010 알 수 없는 커맨드입니다.
3010 Web API 실행을 지원하지 않는 기기입니다. 지원되는 기기 예: CHC, HDM-C070RL
3009 현재 프로젝트 실행 모드가 아닌 HMI 기기에 접속을 시도했습니다.
3012 원격제어 비밀번호가 맞지 않습니다.
3013 스크립트의 구문 오류입니다.
comfilehmi/webapi/index.txt · 마지막으로 수정됨: 2021/07/30 14:08 저자 Comfile Technology