Table of Contents

Web API

이 문서는 Comfile Studio의 <Web_API> 기능을 설명합니다.
Web API는 HTTP 프로토콜을 사용하여 원격지에서 HMI(서버)와 통신하면서 다양한 작업을 수행할 수 있는 기능입니다.

  • HMI 제어하기
  • 내부 변수/내부 메모리 값 읽기
  • HMI에 있는 파일을 웹브라우저로 다운로드/실행하기
  • 웹브라우저에서 실시간 동작 UI 구성하기

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

1. URL 작성하는 방법

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

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

예)

  • 192.168.0.30:9138/script/1234/a=a+1;vars_to_json(“a”)
  • 192.168.0.30/download/<html></html>/storage card/logs/log1.txt

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

1) IP 주소

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

2) 포트번호

포트번호는 서버에서 설정한 값을 사용하며, 생략할 수 있습니다. (생략 시 80으로 간주)

3) 커맨드명

커맨드는 수행할 동작을 결정하며, 다음 종류가 있습니다.

(1) 'script' 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”)

(2) 'open' / 'download'의 경우 서버 HMI의 파일 경로를 지정합니다. 파일 경로는 SD카드의 파일만 가능하며 “storage card/“로 시작해야 합니다. 폴더 구분자는 '\'가 아닌 '/'를 사용합니다.

예)

  • 192.168.0.30:9138/open/<html></html>/storage card/MyWebHmi/index.htm
  • 192.168.0.30:9138/download/<html></html>/storage card/logs.txt

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

웹브라우저 주소창에서는 '#', '%', '\' 문자를 직접 표현하기 어렵기 때문에 다음과 같이 치환하여 사용합니다.

  • '#' → '%23'
  • '%' → '%25'
  • '\' → '%5C' (파일 경로는 '/'로 치환해도 됨)

2. 응답 처리하는 방법

ComfileHMI는 적절한 형식의 'script' 요청이 들어오거나 URL 오류가 있을 때 JSON 형식으로 응답합니다. 'open' / 'download'는 실패한 경우에만 JSON 형식으로 응답합니다.

1) HMI 클라이언트에서 응답 처리

HMI 클라이언트는 수신된 JSON 응답을 자동으로 해석합니다. 원격지 내부 변수값 또는 내부 메모리값이 JSON으로 수신되면 동일한 변수명/번지로 그대로 복사됩니다.

또한, JSON 응답 처리 후 실행할 사용자 액션도 지정할 수 있습니다.

최근 JSON 응답에 대한 정보는 아래 함수로 확인할 수 있습니다.

  • 성공 여부: last_json_result()
  • 에러 코드: last_json_error_code()
  • 에러 메시지: last_json_error_message()

함수 설명: API관련 시스템_함수

2) 웹브라우저에서 응답 처리(HTML / JavaScript / JSON 이해 필요)

download / open 커맨드는 성공 시 브라우저에서 동작이 바로 반영되므로 JSON 처리가 필수는 아닙니다.

하지만 script 커맨드는 응답이 항상 JSON으로 오기 때문에 JSON을 처리할 HTML/JavaScript 코드를 직접 작성해야 합니다.

작성한 HTML 파일은 반드시 원격지 HMI의 SD카드에 위치해야 하며, open 커맨드로 웹브라우저에서 불러옵니다.

쉬운 예제) 변수 a 값과 HMI 메모리 5,6번지 값을 200ms 주기로 읽어 웹브라우저에 표시합니다.

쉬운 예제 HTML 파일 다운로드 쉬운 예제 실행 화면

고급 예제) 웹브라우저 슬라이더로 원격지 HMI 변수 a 값을 쓰고, 그 값을 다시 읽어 게이지 그래프로 표시합니다. (0~100 범위, 초과 시 빨간색)

고급 예제 HTML 파일 다운로드 고급 예제 실행 화면 고급 예제 게이지 표시 화면

<예제 테스트 절차>

  1. sample1.htm 또는 sample2.htm을 다운로드하여 HMI의 storage card 폴더(SD카드 루트)에 복사합니다.
  2. htm 소스 코드 내부의 '서버 주소:포트 번호' 값을 환경에 맞게 변경합니다. (예: 192.168.0.99:9138)
  3. HMI 런타임 [설정 > 서버 > 원격 제어 서버 구동]을 체크하고 네트워크를 설정합니다.
  4. 웹브라우저 주소창에 URL을 입력합니다.

예) 192.168.0.99:9138/open/<html></html>/storage card/sample1.htm

3. JSON 응답 형식

필드명 타입 내용
success boolean 성공 여부. true이면 성공, false이면 실패
vars.{내부 변수명} number vars_to_json()로 요청한 내부 변수 값
vars.{내부 문자열 변수명} string vars_to_json()로 요청한 내부 문자열 변수 값 ('$'로 시작)
mem.{내부 메모리 시작 번지} array mem_to_json()로 요청한 메모리 연속 값
error.code number 오류 코드
error.message string 오류 메시지 (프로젝트 기본 언어에 따라 표시)
filenames array filenames_to_json()로 요청한 파일명 목록
dirnames array dirnames_to_json()로 요청한 폴더명 목록 
예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 스크립트 구문 오류입니다.

키워드: Web_API, ComfileStudio, CHC 시리즈, 펌웨어 3.49, HTTP 통신, script open download, vars_to_json, mem_to_json, JSON 응답, last_json_result

상위 페이지로 가기