====== Web API ====== 이 문서는 Comfile Studio의 기능을 설명합니다. \\ 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//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//storage card/MyWebHmi/index.htm * 192.168.0.30:9138/download//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//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 [[ComfileStudio:index#원격_제어_및_네트워크_기능|상위 페이지로 가기]]