comfilestudio:web_api:index [컴파일 온라인 사용설명서]

이 문서는 읽기 전용입니다. 원본을 볼 수는 있지만 바꿀 수는 없습니다. 문제가 있다고 생각하면 관리자에게 문의하세요.
====== 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()

함수 설명:  
[[..:system_functions:index#11._Web_API_관련_함수_(고급_기능,_CHC_또는_그_상위_모델에서만_지원)|API관련 시스템_함수]]

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

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

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

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

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

{{  :ComfileStudio:Web_API:sample1.htm | 쉬운 예제 HTML 파일 다운로드  }}
{{  :ComfileStudio:Web_API:sample1.png?nolink | 쉬운 예제 실행 화면  }}

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

{{  :ComfileStudio:Web_API:sample2.htm | 고급 예제 HTML 파일 다운로드  }}
{{  :ComfileStudio:Web_API:sample2.png?nolink | 고급 예제 실행 화면  }}
{{  :ComfileStudio:Web_API:sample2b.png?nolink | 고급 예제 게이지 표시 화면  }}

<예제 테스트 절차>
  - sample1.htm 또는 sample2.htm을 다운로드하여 HMI의 storage card 폴더(SD카드 루트)에 복사합니다.
  - htm 소스 코드 내부의 '서버 주소:포트 번호' 값을 환경에 맞게 변경합니다. (예: 192.168.0.99:9138)
  - HMI 런타임 [설정 > 서버 > 원격 제어 서버 구동]을 체크하고 네트워크를 설정합니다.
  - 웹브라우저 주소창에 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()로 요청한 폴더명 목록 |

<code>
예1) 성공했을 경우
{
	"success": true,
	"vars": {
		"temperature" : 16.7,
		"$city" : "Seoul"
	},
	"mem" : {
		"20" : [31,43,21]
	}
}

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

===== 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

[[ComfileStudio:index#원격_제어_및_네트워크_기능|상위 페이지로 가기]]
컴파일 온라인 사용설명서

공통사항

위젯

액션

이벤트

시스템 함수

도형및 그래픽 편집

리소스 관리

시스템 함수

원격 제어 및 네트워크 기능

편의 기능

공통사항

위젯

액션

이벤트

시스템 함수

도형및 그래픽 편집

리소스 관리

시스템 함수

원격 제어 및 네트워크 기능

편의 기능

사이트 도구

문서 도구
